Responses & Errors

Success Responses

All successful responses use the ApiResponse<T> envelope:

{
  "data": { ... },
  "meta": { "version": "1.0" }
}

The meta field is optional and omitted when not applicable.

Paginated Responses

List endpoints use CursorPage<T> with cursor-based pagination:

{
  "data": [ ... ],
  "pagination": {
    "has_next": true,
    "has_previous": false,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xNVQxMDozMDowMFoiLCJpZCI6ImFiYzEyMyJ9",
    "previous_cursor": null,
    "total_count": 142
  }
}

Error Responses

All errors follow RFC 7807 Problem Details:

{
  "type": "urn:akili:error:not_found",
  "title": "Product not found",
  "status": 404,
  "detail": "Not found: product 550e8400-e29b-41d4-a716-446655440000",
  "instance": "req_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

Validation errors (422) include per-field details:

{
  "type": "urn:akili:error:validation_failed",
  "title": "Request validation failed",
  "status": 422,
  "detail": "Validation failed",
  "instance": "req_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "errors": [
    { "field": "/name", "message": "Name is required", "code": "required" },
    { "field": "/version", "message": "Invalid semver format", "code": "invalid_format" }
  ]
}

Common Query Parameters

Pagination

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (1-100)
`after`	string	—	Opaque cursor: return items after this position
`before`	string	—	Opaque cursor: return items before this position

after and before are mutually exclusive. Providing both returns a 400 error.

Sorting

Default sort order is created_at DESC, id DESC (newest first with deterministic tiebreak). The cursor encodes (created_at, id) for stable, gap-free pagination.

Status Codes

Code	Meaning	Content-Type
`200`	Success (GET, PUT)	`application/json`
`201`	Created (POST)	`application/json`
`202`	Accepted (async operations: deploy, trigger, replay)	`application/json`
`204`	No Content (DELETE, preflight)	—
`400`	Bad request (malformed JSON, invalid cursor)	`application/problem+json`
`401`	Unauthorized (missing/invalid/expired JWT)	`application/problem+json`
`403`	Forbidden (insufficient role, suspended tenant)	`application/problem+json`
`404`	Not found (within tenant scope)	`application/problem+json`
`409`	Conflict (duplicate, invalid state transition)	`application/problem+json`
`413`	Payload too large (manifest upload > 10 MB)	`application/problem+json`
`422`	Validation failed (field-level errors)	`application/problem+json`
`429`	Rate limit exceeded	`application/problem+json`
`500`	Internal server error	`application/problem+json`
`503`	Service unavailable (dependency down)	`application/problem+json`
`504`	Gateway timeout (Dagster, Redpanda unresponsive)	`application/problem+json`