---
title: "Create a project from a brief"
method: POST
path: "/projects"
tags: ["Projects"]
---

# Create a project from a brief

`POST /projects`

## Request

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

Scope `projects.write`. Starts a build and answers an admission receipt; the build runs after the answer and spends the credits of your plan, as the same brief typed into the editor would. Follow it with GET /operations/{requestId}.

## Request body

- Instruction
  - `prompt` string, required: The brief, or the next instruction, in any language. It is handed to VULK unchanged.
  - `model` string: A model id from GET /models, or `auto`. Omit it to let VULK choose. A model your plan does not include answers 402.
  - `requestId` string, uuid: A UUID v4 you make. Send the same requestId to retry a submit whose answer was lost: the API returns the operation it already created instead of starting a second one. Omitted, VULK makes one.

## Response `202`

Admission receipt. The build runs after this answer; follow it with GET /operations/{requestId}. `accepted: false` with `operationStatus: "unconfirmed"` means VULK had not recorded the operation within the wait: read the operation, then retry with exactly the same requestId and body.

- AdmissionReceipt
  - `requestId` string, uuid, required
  - `accepted` boolean, required: True when VULK recorded the operation.
  - `operationStatus` 'running' | 'waiting' | 'done' | 'failed' | 'orphan' | 'unconfirmed' | 'null', nullable, required: `unconfirmed` when `accepted` is false.
  - `projectId` string
  - `editorUrl` string, uri
  - `nextAction` string, required: What to do next, in a sentence written for the caller.

## Other responses

- `400`: A parameter or body field is wrong; the sentence names it (code VALIDATION_ERROR).
- `401`: No key, a malformed key, or a revoked or expired one (code UNAUTHORIZED).
- `402`: The plan or credit balance does not cover the request (code PAYMENT_REQUIRED).
- `403`: The key lacks the scope the endpoint needs (code FORBIDDEN).
- `413`: The body is over 64 KB (code PAYLOAD_TOO_LARGE).
- `429`: Over 60 requests in a minute; wait `retryAfter` seconds (code RATE_LIMITED).
- `503`: Generation or a dependency is temporarily unavailable; nothing was submitted (code SERVICE_UNAVAILABLE).

---

[API](https://skmtc.dev/vulk/apis/vulk-rest-api.md) · [All operations](https://skmtc.dev/vulk/apis/vulk-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vulk/apis/vulk-rest-api/revisions/b30510c5149c?raw)