---
title: "Create a project"
method: POST
path: "/api/v1/projects"
tags: ["projects"]
---

# Create a project

`POST /api/v1/projects`

## Request

- Base URL: `https://goshipyard.app`
- URL: `https://goshipyard.app/api/v1/projects`
- Auth: HTTP bearer

Send `application/json` for a text-only project, or `multipart/form-data` to include images (`hero` + up to two `extra`). The project is owned by the key holder.

## Request body

- CreateProjectRequest
  - `title` string, required: Project name.
  - `pitch` string, required: One-line elevator pitch.
  - `url` string, uri, required: Public http(s) link to the project.
  - `repo_url` string, uri: Optional source repo.
  - `category` 'devtools' | 'ai' | 'games' | 'productivity' | 'design' | 'social' | 'data' | 'creative' | 'other'
  - `body` string: Optional long-form markdown.
  - `slug` string: Optional URL slug; derived from the title (auto-suffixed) when omitted. Conflicts return 409.

## Response `201`

Created.

- Project
  - `id` string, required
  - `slug` string, required
  - `owner_handle` string, required
  - `title` string, required
  - `pitch` string, required
  - `body` string, required: Long-form markdown.
  - `url` string, uri, required
  - `repo_url` string, required
  - `category` 'devtools' | 'ai' | 'games' | 'productivity' | 'design' | 'social' | 'data' | 'creative' | 'other', required
  - `upvotes` integer, required
  - `reviews` integer, required
  - `featured` boolean, required
  - `voted` boolean: Whether the caller has upvoted this project. Present on single-project reads (GET /projects/{id}) and the upvote endpoints; omitted from list responses.
  - `created_at` string, date-time, required
  - `images` ProjectImage[], required
    - `ordinal` integer, required: 0 = hero, 1–2 = gallery.
    - `url` string, uri, required
  - `html_url` string, uri, required: Human-facing project page.

## Other responses

- `401`: Missing or invalid API key.
- `409`: Conflict — e.g. slug already taken, or delete blocked by an active bounty.
- `422`: Request failed validation.
- `429`: Too many requests — slow down.

---

[API](https://skmtc.dev/goshipyard/apis/shipyard-api.md) · [All operations](https://skmtc.dev/goshipyard/apis/shipyard-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goshipyard/apis/shipyard-api/revisions/8f12372f1065?raw)