API: tickets

Status: GA Access: token required API contract: 0.3.0 · capability 2026-09-03.1 View as Markdown Open in Claude Open in ChatGPT

`GET /api/v1/tickets`

List Board

Open as a page →

The owner board — defects/incidents by default, or a vote-ranked suggestion backlog with ?kind=suggestion. Team-readable (owner + team, the defect section of the tasks board; agents still get 403.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`kind`	query	no	`string \| null`	defect\|incident\|suggestion (default: the defect/incident board)
`status`	query	no	`string \| null`	open\|closed
`component`	query	no	`string \| null`
`area`	query	no	`string \| null`	platform\|pipelines\|instances\|other
`severity`	query	no	`string \| null`
`since`	query	no	`string \| null`	tickets created at/after this UTC time
`limit`	query	no	`integer`

Responses:

Code	Meaning	Body
`200`	Successful Response	`array of TicketRead`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

`POST /api/v1/tickets`

File Ticket

Open as a page →

Intake one report; return a bare 202.

Write-only fire-and-forget: no ticket id, no dedup verdict — a hostile or looping reporter gets nothing back to react to. Over the flood cap → 429; an oversized body → 413.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`Idempotency-Key`	header	no	`string`	Optional.

Request body: application/json — schema TicketReportIn

Field	Type	Required
`actual`	`string \| null`	no
`alternatives`	`array of string \| null`	no
`area`	`string \| null`	no
`behavior_cases`	`array of string \| null`	no
`body`	`string \| null`	no
`component`	`string \| null`	no
`contract_guid`	`integer \| null`	no
`environment`	`object \| null`	no
`evidence`	`array of EvidenceItem \| null`	no
`expected`	`string \| null`	no
`expected_benefit`	`string \| null`	no
`fingerprint`	`string \| null`	no
`kind`	`string \| null`	no
`payload`	`object \| null`	no
`problem`	`string \| null`	no
`proposed_change`	`string \| null`	no
`run_guid`	`integer \| null`	no
`severity`	`string \| null`	no
`spec_ref`	`string \| null`	no
`steps_to_reproduce`	`array of string \| null`	no
`title`	`string`	yes

Example:

{
  "actual": "The Description column is empty",
  "component": "portal",
  "environment": {
    "commit": "dcaf59d1"
  },
  "evidence": [
    {
      "type": "url",
      "url": "https://enterium-developer-docs.pages.dev/developers/mcp/tools/entherium_create_task/"
    }
  ],
  "expected": "Every parameter has a description",
  "kind": "defect",
  "severity": "sev3",
  "steps_to_reproduce": [
    "Open /developers/mcp/tools/entherium_create_task/",
    "Look at the Parameters table"
  ],
  "title": "Tool page renders an empty Description column"
}

Responses:

Code	Meaning	Body
`202`	Successful Response	`object`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

`PATCH /api/v1/tickets/{guid}`

Transition Ticket

Open as a page →

Resolve / dismiss / promote a ticket, state-machine-guarded.

Owner-only. An illegal transition (e.g. closing an already-closed ticket) → 409.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`guid`	path	yes	`integer`
`Idempotency-Key`	header	no	`string`	Optional.

Request body: application/json — schema TicketPatch

Field	Type	Required
`action`	`"resolve" \| "dismiss" \| "promote" \| "target" \| "reopen" \| "edit"`	yes
`description`	`string \| null`	no
`promoted_to`	`string \| null`	no
`resolution`	`string \| null`	no
`severity`	`"sev1" \| "sev2" \| "sev3" \| "sev4" \| null`	no
`spec_ref`	`string \| null`	no
`title`	`string \| null`	no

Example:

{
  "action": "resolve",
  "resolution": "fixed in build 0.3.1; verified on the live URL"
}

Responses:

Code	Meaning	Body
`200`	Successful Response	`TicketRead`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`