Skip to main content
POST
/
v1
/
runs
Start a spec-to-PR run
curl --request POST \
  --url https://api.usezombie.com/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mode": "pull_request",
  "requested_by": "<string>",
  "idempotency_key": "<string>",
  "spec_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "spec_markdown": "<string>",
  "base_commit_sha": "<string>"
}
'
{
  "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idempotency_key": "<string>",
  "status": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "spec_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

Obtain a token via the CLI auth flow (POST /v1/auth/sessions) or GitHub OAuth

Body

application/json
​
workspace_id
string<uuid>
required

Target workspace

​
mode
enum<string>
required

Run mode — currently only pull_request is supported

Available options:
pull_request
​
requested_by
string
required

Identity of the user or system that requested the run

​
idempotency_key
string
required

Client-generated key for at-most-once execution

​
spec_id
string<uuid> | null

Reference to an existing spec. Mutually exclusive with spec_markdown.

​
spec_markdown
string | null

Inline spec content in Markdown. Mutually exclusive with spec_id.

​
base_commit_sha
string | null

Pin the run to a specific base commit. Uses HEAD of default branch if null.

Response

Run queued

​
run_id
string<uuid>
required
​
workspace_id
string<uuid>
required
​
idempotency_key
string
required
​
status
string
required
Allowed value: "queued"
​
request_id
string<uuid>
required
​
spec_id
string<uuid> | null