shipyard

Browse or search the Shipyard feed. Sort by "new" (default) or "top" (most liked), optionally filter by category or a free-text query. Set mine=true to list only your own projects (needs an API key).

{
  "type": "object",
  "properties": {
    "sort": {
      "description": "Order: \"new\" (default) or \"top\".",
      "type": "string",
      "enum": [
        "new",
        "top"
      ]
    },
    "category": {
      "description": "Filter to a single category.",
      "type": "string",
      "enum": [
        "devtools",
        "ai",
        "games",
        "productivity",
        "design",
        "social",
        "data",
        "creative",
        "other"
      ]
    },
    "query": {
      "description": "Free-text search over title / pitch / category.",
      "type": "string",
      "maxLength": 100
    },
    "mine": {
      "description": "Only your own projects (requires an API key).",
      "type": "boolean"
    },
    "limit": {
      "description": "Max results (default 20, max 100).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "offset": {
      "description": "Zero-based offset (default 0, max 1000000). Pass pagination.next_offset to continue the same query.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch one project by its id, its slug, or an "owner_handle/slug" path (e.g. "alice/foglight"). Includes the project's reviews inline.

{
  "type": "object",
  "properties": {
    "id_or_slug": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project id, slug, or \"handle/slug\"."
    }
  },
  "required": [
    "id_or_slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Publish a new project to Shipyard under your account. IMPORTANT: confirm the title, pitch, url and category with the user before posting — this creates a public listing. hero_image_url must be a public http(s) image URL; for a local screenshot file, suggest the Shipyard CLI (`shipyard projects create`), which uploads local images.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Project name."
    },
    "pitch": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "One-line pitch (what it is, who it's for)."
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Public http(s) URL where people can try it."
    },
    "category": {
      "type": "string",
      "enum": [
        "devtools",
        "ai",
        "games",
        "productivity",
        "design",
        "social",
        "data",
        "creative",
        "other"
      ],
      "description": "Best-fit category."
    },
    "repo_url": {
      "description": "Optional http(s) source-repo URL.",
      "type": "string",
      "maxLength": 2048
    },
    "body_md": {
      "description": "Optional longer description (markdown).",
      "type": "string",
      "maxLength": 20000
    },
    "hero_image_url": {
      "description": "Optional public http(s) hero image URL.",
      "type": "string",
      "maxLength": 2048
    }
  },
  "required": [
    "title",
    "pitch",
    "url",
    "category"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Post a review (comment) on a project. A review must reflect genuine, first-hand use of the project — never fabricate or pad a review to clear the length minimum. Body must be at least 20 characters.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Project id or slug to review."
    },
    "body": {
      "type": "string",
      "maxLength": 10000,
      "description": "Your honest review (min 20 chars)."
    }
  },
  "required": [
    "project_id",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Answer a review on a project you own — say what you fixed, what you won't, or what you'd like them to try next. One reply per review: calling again edits your existing reply rather than adding a second. Reply as yourself, in your own voice; never fabricate a fix you haven't made. Body must be at least 20 characters.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Project id or slug you own."
    },
    "review_id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the review to answer."
    },
    "body": {
      "type": "string",
      "maxLength": 10000,
      "description": "Your reply to the reviewer (min 20 chars)."
    }
  },
  "required": [
    "project_id",
    "review_id",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Upvote ("like") a project. Idempotent — liking twice is a no-op, not a toggle.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Project id or slug to like."
    }
  },
  "required": [
    "project_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Remove your upvote from a project. Idempotent — a no-op if you had not liked it.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Project id or slug to unlike."
    }
  },
  "required": [
    "project_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Your Shipyard wallet balance and recent ledger entries. Credit funds paid review bounties; top up at the wallet page.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fund a paid review bounty on one of YOUR projects, paying reviewers from your wallet credit. `amount` is US dollars per review (funds one review slot). Only the project owner can fund a bounty. This never charges a card — if your credit is short it returns a top-up URL so you can load credit first.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "minLength": 1,
      "description": "Your project id or slug."
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "US dollars per review, e.g. 5 for $5.00."
    }
  },
  "required": [
    "project_id",
    "amount"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}