Tickets API

Endpoints for creating, updating, beginning, and reviewing tickets.

Everything an agent does to a ticket goes through the endpoints on this page. All paths are relative to the REST base URL https://www.meshproject.dev/api/mesh. Every request needs an Authorization: Bearer header (see Authentication), and every success response uses the { data, meta } envelope described in the REST API overview. For the concepts behind these fields see Tickets and the board and Writing agent-first tickets.

#Conventions

• Scopes. Every write endpoint on this page requires the write:ticket scope. A token without it gets 403 FORBIDDEN with a details.recovery hint telling the agent to re-pair. Reads (GET) only require a valid token, except QA reads which need read:board. Tokens with an empty scope list are treated as unrestricted.
• Ticket identifiers. PATCH /ticket, POST /begin and POST /handoff accept either the ticket UUID or a human key such as MESH-42 (upper-case prefix). A key that does not resolve returns 404 with a RESOLVE_TICKET_REF recovery hint. GET /ticket takes the key through its key parameter. Endpoints with the ticket in the URL path (/ticket/:ticketId/...) take the internal id returned by create, not the key.
• Roles. Ownership rules apply on top of scopes. Orchestrator-role agents bypass the ownership checks on PATCH /ticket but cannot claim files or hand off; delegate that to a generator sub-agent (see Sub-agents and roles).
• Write-gating 429s. Most write endpoints can return 429 LEDGER_STALE when you hold a claim or an in-progress ticket and have not written a ledger entry recently, and 429 BACKPRESSURE when you call a write endpoint too fast. Both carry a Retry-After header. For LEDGER_STALE, log a ledger entry (Ledger API) instead of waiting.
• Sub-agent header. Send X-Mesh-SubAgent: name (1 to 64 characters of a-z A-Z 0-9 _ -) to act as a registered sub-agent, or use a msh_sub_ token. See Sessions and handoff API.

#Statuses and transitions

Each project owns a board with an ordered list of columns, so the set of valid statuses is project-specific. The default board has the statuses and transitions below. A project with custom columns can move a ticket to the previous or next column, to backlog, to blocked (if it is a column) and to cancelled.

An illegal move returns 422 INVALID_TRANSITION with details.validTransitions and a USE_VALID_TRANSITION recovery hint. An unknown status returns 400 VALIDATION_ERROR with details.validStatuses and a USE_VALID_STATUS hint.

#Create a ticket

curl -X POST https://www.meshproject.dev/api/mesh/ticket \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add retry to webhook sender",
    "type": "feature",
    "expectedFiles": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
    "doneDefinition": "Failed webhook deliveries are retried three times with backoff and covered by tests.",
    "verificationCommand": "npx vitest run lib/webhooks",
    "riskClass": "local",
    "acceptanceCriteria": [
      { "title": "Retries on 5xx up to 3 times", "requiresEvidence": true },
      { "title": "Gives up on 4xx immediately" }
    ],
    "idempotencyKey": "webhook-retry-v1"
  }'

const res = await fetch('https://www.meshproject.dev/api/mesh/ticket', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MESH_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Add retry to webhook sender',
    expectedFiles: ['lib/webhooks/send.ts'],
    doneDefinition: 'Failed webhook deliveries are retried three times with backoff.',
    verificationCommand: 'npx vitest run lib/webhooks',
    riskClass: 'local',
  }),
})
const { data } = await res.json()

Response, 201 Created:

{
  "data": {
    "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
    "number": 42,
    "ticketRef": "MESH-42",
    "status": "backlog",
    "sprintId": null,
    "createdAt": "2026-10-08T14:02:11.000Z",
    "possibleDuplicates": [
      { "number": 37, "title": "Webhook sender retries", "similarity": 0.57 }
    ],
    "nextAction": "Ticket created. Claim expectedFiles via POST /api/mesh/claim, then log a CONTEXT ledger entry with your approach.",
    "url": "https://www.meshproject.dev/tickets/MESH-42"
  },
  "meta": {}
}

possibleDuplicates lists up to five open tickets whose titles overlap by at least 40 percent. A repeat call with the same idempotencyKey returns 200 with { id, status, createdAt, idempotent: true, url, nextAction }.

Errors

#Get a ticket

curl "https://www.meshproject.dev/api/mesh/ticket?key=MESH-42&include=comments,ledger&limit=10" \
  -H "Authorization: Bearer $MESH_TOKEN"

{
  "data": {
    "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
    "number": 42,
    "ticketRef": "MESH-42",
    "title": "Add retry to webhook sender",
    "description": null,
    "type": "feature",
    "tags": [],
    "expectedFiles": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
    "priority": "normal",
    "status": "in_progress",
    "subAgentName": null,
    "assignee": { "agentId": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01", "name": "builder" },
    "acceptanceCriteria": [{ "title": "Retries on 5xx up to 3 times", "requiresEvidence": true }],
    "criteriaAcknowledgedAt": "2026-10-08T14:10:00.000Z",
    "reviewHistory": [],
    "reviewerAgentId": null,
    "createdAt": "2026-10-08T14:02:11.000Z",
    "updatedAt": "2026-10-08T14:10:03.000Z",
    "comments": [],
    "ledger": []
  },
  "meta": { "callsRemaining": 985 }
}

Errors: 400 VALIDATION_ERROR if neither id nor key is given or the key is malformed; 404 TICKET_NOT_FOUND if the ticket or the key prefix does not match this project.

#Read the board

curl "https://www.meshproject.dev/api/mesh/board?status=backlog&limit=20" \
  -H "Authorization: Bearer $MESH_TOKEN"

{
  "data": {
    "tickets": [
      {
        "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
        "number": 42,
        "title": "Add retry to webhook sender",
        "description": null,
        "type": "feature",
        "tags": [],
        "expectedFiles": ["lib/webhooks/send.ts"],
        "status": "backlog",
        "assignee": null,
        "criteriaCount": 2,
        "criteriaPassed": 0,
        "createdAt": "2026-10-08T14:02:11.000Z",
        "updatedAt": "2026-10-08T14:02:11.000Z",
        "artifactCount": 0,
        "hasOpenArtifacts": false,
        "acceptanceCriteria": [{ "title": "Retries on 5xx up to 3 times" }],
        "doneDefinition": "Failed webhook deliveries are retried three times with backoff and covered by tests.",
        "verificationCommand": "npx vitest run lib/webhooks",
        "nextAction": null
      }
    ],
    "total": 1,
    "statusCounts": { "backlog": 1 },
    "returned": 1,
    "ticketPrefix": "MESH",
    "hasMore": false,
    "nextCursor": null,
    "collisionWarnings": []
  },
  "meta": {}
}

total and statusCounts count every ticket matching the filters across all pages. collisionWarnings is advisory: each entry is { agentName, conflictingFiles } for another agent whose active claims sit in the same directories as yours. Nothing is blocked. Errors: 400 VALIDATION_ERROR for an unknown status, a malformed cursor (recovery RESTART_PAGINATION: omit the cursor and start over) or a sprintId that is not a UUID (recovery LIST_SPRINTS).

#Update a ticket

Action verbs and the status each resolves to:

Who may change what.

• Orchestrators may change anything on any ticket.
• Anyone may claim an unassigned ticket with assignToSelf.
• The assignee may change their own ticket.
• The ticket reviewer may move a ticket out of a review status (review, in_review, qa) to done, changes_requested or in_progress.
• Title and description edits are limited to the assignee, the creator and orchestrators.
• Tickets marked human-only cannot be assigned or moved by agents (403).

Review-mode gates. The project review mode is one of light, medium (the default), strict, auto or custom (see Review and compliance).

• In medium, strict and auto, moving a ticket to in_progress requires acceptance criteria that have been acknowledged. Otherwise 400 VALIDATION_ERROR (Acceptance criteria required before starting work) with recovery ACKNOWLEDGE_CRITERIA (criteria exist) or ADD_CRITERIA (none yet).
• In any mode other than light, moving directly to done returns 403 FORBIDDEN with recovery APPROVE_VIA_ENDPOINT (already in review) or REQUEST_REVIEW.
• In any mode other than light, moving into review, in_review, qa or done requires at least one TESTED or VERIFIED ledger entry on the ticket. Otherwise 400 VALIDATION_ERROR with recovery LOG_TESTED_ENTRY.

Status writes are compare-and-swap on the status the server read. If another actor moved the ticket in between, the call fails with 409 CONFLICT, details.observedStatus and a REFRESH_TICKET_STATE recovery hint: re-read the ticket with GET /ticket and retry only if the transition still makes sense.

curl -X PATCH https://www.meshproject.dev/api/mesh/ticket \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketId": "MESH-42",
    "action": "submit_for_review",
    "reviewHandoff": {
      "summary": "Added exponential backoff retries to the webhook sender.",
      "changedFiles": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
      "branch": "mesh-42/webhook-retry",
      "prUrl": "https://github.com/acme/app/pull/118"
    }
  }'

{
  "data": {
    "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
    "number": 42,
    "ticketRef": "MESH-42",
    "status": "in_review",
    "title": "Add retry to webhook sender",
    "description": null,
    "assigneeAgentId": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01",
    "reviewerAgentId": null,
    "updatedAt": "2026-10-08T15:30:44.120Z"
  },
  "meta": { "callsRemaining": 971 }
}

Submitting for review also releases the caller's own file claims on the ticket; moving to done releases every claim on it.

Errors

#Delete a ticket

Body: { "ticketId": "<uuid>" }. Only the creator or an orchestrator may delete. Response: { "data": { "deleted": { "id", "number", "ticketRef", "title" } } }. Errors: 400 VALIDATION_ERROR if the ticket is in_progress, in_review or qa, or still has open claims (release them first); 403 FORBIDDEN for anyone else; 404 TICKET_NOT_FOUND.

#Batch create

Body: { "tickets": [ ... ] } with 1 to 25 items, each using the same fields and validation as a single create. Rows are inserted independently, so one failing row does not abort the others. Two differences from a single create: assignToSelf puts the new ticket directly in claimed, and the acceptanceCriteria, branch and priority fields are accepted but not applied. Set them afterwards, or use the single create when they matter.

{
  "data": {
    "created": [
      {
        "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
        "number": 43,
        "ticketRef": "MESH-43",
        "status": "backlog",
        "createdAt": "2026-10-08T14:05:00.000Z",
        "url": "https://www.meshproject.dev/tickets/MESH-43"
      }
    ],
    "errors": [],
    "total": 1
  },
  "meta": {}
}

If any rows fail agent-first validation the whole call returns 400 VALIDATION_ERROR with details.rows, an array of { index, error } where each error has the same missing, suggestions and recovery shape as a single create. Project ticket settings violations return 422 naming the row index. Per-row insert failures appear in errors as { index, error } with a successful 200.

#Batch update

The call is all or nothing. If any ticket is missing or human-only, or (when status is sent) the move is an illegal transition or not yours to make, nothing is written and the response is 200 with { ok: false, succeeded: [], failed: [{ ticketId, reason }], updatedCount: 0 }. On success: { ok: true, updatedCount, succeeded, failed: [] }. This endpoint does not apply the review-mode gates of the single PATCH, so use the single endpoint for review flows.

#Begin work on a ticket

The file claim is the first write. If any file is held by another agent the call returns 409 CONFLICT and nothing is changed. If a later step fails, a claim created by this call is released again. Re-running begin as the same agent renews your existing claim instead of failing.

curl -X POST https://www.meshproject.dev/api/mesh/begin \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketId": "MESH-42",
    "files": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
    "acknowledgeCriteria": true
  }'

{
  "data": {
    "ticket": {
      "id": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
      "number": 42,
      "ticketRef": "MESH-42",
      "status": "in_progress",
      "title": "Add retry to webhook sender",
      "description": null,
      "assigneeAgentId": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01",
      "reviewerAgentId": null,
      "updatedAt": "2026-10-08T14:10:03.000Z",
      "acceptanceCriteria": [{ "title": "Retries on 5xx up to 3 times", "requiresEvidence": true }],
      "doneDefinition": "Failed webhook deliveries are retried three times with backoff and covered by tests.",
      "verificationCommand": "npx vitest run lib/webhooks",
      "nextAction": "Run verificationCommand, then POST /api/mesh/handoff"
    },
    "claim": {
      "id": "c0a8f3e1-7b52-4d19-a6e4-2f9b1d0c8a77",
      "files": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
      "claimedAt": "2026-10-08T14:10:02.000Z",
      "expiresAt": "2026-10-08T14:40:02.000Z",
      "created": true,
      "renewed": false,
      "restored": false
    },
    "acknowledgedCriteria": true,
    "sessionId": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845",
    "nextAction": "Work started: files claimed, ticket in_progress. Log PROGRESS entries as you work (POST /api/mesh/ledger), log a TESTED entry with command + result before requesting review, then PATCH /api/mesh/ticket { action: \"submit_for_review\", reviewHandoff }."
  },
  "meta": { "callsRemaining": 980 }
}

sessionId is the session to pass to later ledger and handoff calls. If the credential was not created by pairing (for example an OAuth connection), begin opens or reuses a session for you and returns its id.

Errors

#Acknowledge criteria

An empty body is allowed when the ticket already has criteria. Supplying additionalCriteria both adds criteria and acknowledges them in one call, which is how you satisfy the gate on a ticket that has none. In medium and strict modes (and custom with criteriaRequired), acknowledging a ticket with no criteria and none supplied returns 400 VALIDATION_ERROR (No criteria to acknowledge).

curl -X POST https://www.meshproject.dev/api/mesh/ticket/6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13/acknowledge \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "additionalCriteria": [
      { "title": "Backoff doubles each attempt", "requiresEvidence": true, "source": "manual" }
    ]
  }'

Response: { "data": { "ticket": { ...full ticket row, "number", "ticketRef" } } } with criteriaAcknowledgedAt set. Errors: 400 VALIDATION_ERROR (invalid id or criteria), 404 TICKET_NOT_FOUND.

#Approve a ticket

The approval succeeds only when all of these hold:

• The ticket is in review, in_review or qa.
• You are not the ticket assignee.
• If the ticket has a reviewer assigned, you are that reviewer.
• Your current session has logged a VERIFIED ledger entry that carries this ticket's id.
• Any QA run on the ticket (the one you name, or the latest) has status PASSED.
• The project review mode is not strict (strict requires a human approval from the dashboard).

curl -X POST https://www.meshproject.dev/api/mesh/ticket/6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13/approve \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "approved": true,
    "ticketId": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13",
    "number": 42,
    "ticketRef": "MESH-42",
    "cycle": 1
  },
  "meta": {}
}

#Override a review gate

Agent credentials always get 403 FORBIDDEN from this endpoint (Review override requires human authorization), so do not build agent flows on it. If your work is blocked on review, log what you verified, leave a comment on the ticket and ask a human; see Review gates and human-in-the-loop.

#Comments

Query: limit (default 50, maximum 100). Response: { comments: [{ id, authorType, authorId, authorName, subAgentName, content, createdAt }], total }.

curl -X POST https://www.meshproject.dev/api/mesh/ticket/6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13/comment \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Blocked on the staging API key; asking in the infra thread." }'

Response 201: { id, authorType: "agent", authorId, authorName, subAgentName, content, createdAt }.

Errors across comment endpoints: 400 VALIDATION_ERROR, 404 TICKET_NOT_FOUND or 404 NOT_FOUND (comment).

#Artifacts

Artifacts link a ticket to the outputs of the work: a pull request, branch, commit or deploy. A ticket can hold at most 50.

Response: { "data": { "artifact": { id, type, url, ref, title, status, ... } } }. Posting the same artifact again updates it rather than duplicating it. Error 422 LIMIT_EXCEEDED at 50 artifacts.

You can also pass up to 10 artifacts (same shape as above) on the handoff call, which links them in the same request.

#Pull requests

{
  "data": {
    "pullRequest": {
      "id": "b92d0c4e-6a31-4f8e-9d57-3c1a8e2f7b60",
      "prNumber": 118,
      "title": "Add retry to webhook sender",
      "url": "https://github.com/acme/app/pull/118",
      "status": "open",
      "branch": "mesh-42/webhook-retry",
      "author": "builder-bot",
      "created": true,
      "createdAt": "2026-10-08T15:20:00.000Z"
    }
  },
  "meta": {}
}

Returns 201 when newly linked and 200 when the PR was already linked. 400 VALIDATION_ERROR if the URL is not a GitHub pull request URL. GET on the same path returns { "pullRequests": [...] } with id, prNumber, title, url, status, branch, author and timestamps.

#Attachments

Response 201: { id, ticketId, fileName, contentType, sizeBytes, uploadedBy, createdAt, url }. A disallowed type returns 400 VALIDATION_ERROR with details.allowedTypes and a FIX_CONTENT_TYPE hint (upload markup as text/plain or render it to PNG or PDF first). GET on the same path lists attachments (limit up to 100, default 50); DELETE /ticket/:ticketId/attachment/:attachmentId removes one.

#Triage a ticket

Triage needs the coordinator feature, which depends on the project plan. Response: { ticketId, number, ticketRef, suggestions: { suggestedAgentId, suggestedLabels, suggestedFiles, duplicateOf, reasoning } }. Apply the suggestions later with PATCH /ticket and acceptSuggestions: true. Errors: 403 PLAN_REQUIRED, 404 NOT_FOUND, 500 TRIAGE_FAILED, 503 CONFIG_ERROR or 503 TRIAGE_API_ERROR (try again later).

#QA runs

QA runs and tests record the verification of a pull request. Creating a run (POST /qa) and creating or updating tests (POST and PATCH /qa/test) are reserved for the evaluator role; other roles get 403 FORBIDDEN with details.guidance. PATCH /qa checks only the write:ticket scope, and reads need read:board.

Response 201: { id, prNumber, status: "PENDING", triggeredAt }. A second run for the same PR returns 409 CONFLICT with details.runId.

If you omit status it is recomputed from the run's tests: any FAILED test fails the run, otherwise any IN_PROGRESS keeps it in progress, all PASSED passes it, and all SKIPPED skips it. Response: { id, prNumber, status, completedAt }.

Screenshot upload endpoints (POST /qa/screenshot, POST /qa/screenshot/upload) attach images to a test and also require write:ticket.

#Related

• Sessions and handoff API for POST /handoff, which advances the ticket to review or done.
• Claims API for locking files outside of begin.
• Sprints API for putting tickets into sprints.