Create a handoff ticket

POST

/projects/{id}/tickets

curl --request POST \
  --url https://example.com/api/projects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/tickets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "description": "example", "request_type": "bug", "roles": [ "frontend" ], "priority": "low", "blocking": false, "evidence": {}, "suggested_resolution": "example", "implementation_notes": "example", "actor_role": "example", "actor_id": "example", "source": "example", "idempotency_key": "example" }'

• AppHandoff API

Authorizations

• bearerApiKey
• cookieAuth

Parameters

Path Parameters

id

required

string format: uuid

Project UUID

Request Body ^required

Media type application/json

object

title

required

string

>= 5 characters <= 140 characters

description

required

string

>= 10 characters <= 5000 characters

request_type

required

string

Allowed values: bug clarification_needed decision_needed feature_request

roles

Explicit role assignments (required for MCP bot ticket creation).

Array<string>

Allowed values: frontend backend design devops qa other

priority

required

string

Allowed values: low medium high

blocking

required

boolean

evidence

object

key

additional properties

any

suggested_resolution

string

<= 2000 characters

implementation_notes

Implementation guidance for the assignee

string

<= 5000 characters

actor_role

Optional actor role; defaults to user in portal.

string

actor_id

Optional actor id; defaults to current user in portal.

string

source

Optional source; defaults to portal in portal API.

string

idempotency_key

Client-supplied idempotency key. If a ticket was already created with this key in this project, the prior response is replayed and _idempotent_replay is true.

string

<= 128 characters

Responses

201

Created ticket

Media type application/json

object

ticket

required

object

id

required

string format: uuid

status

required

string

created_at

required

string format: date-time

similar_existing

Open tickets in this project whose embeddings are >=0.65 cosine similar to the new ticket. Hint only — the new ticket was still created.

Array<object>

object

ticket_ref

required

string

title

required

string

similarity

required

number

status

required

string

stage

required

string

_idempotent_replay

Present and true when the idempotency_key matched a prior response.

boolean

400

Invalid request

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number

401

Not authenticated

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number

reconnect

True if re-linking GitHub may fix the issue

boolean

403

Forbidden

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number