Conventions

This page documents the cross-cutting rules that apply to the public API.

Example values

Examples throughout the API docs use sample IDs, keys, and timestamps to show shape and type. Treat field names, field presence, accepted parameters, and status codes as authoritative.

Headers

Bearer authentication

All /v1 endpoints require:

Authorization: Bearer <access-token>

Content types

• OAuth endpoints require application/x-www-form-urlencoded
• /v1 write endpoints accept application/json
• JSON property names are camelCase, except OAuth responses which use protocol-standard snake_case fields such as access_token

Response shapes

Collections

Collection endpoints return:

{
  "results": [],
  "pagination": {
    "pageSize": 100,
    "cursor": "",
    "nextCursor": "",
    "hasMore": false,
    "returnedCount": 0,
    "totalCount": 0
  }
}

Details

Detail endpoints return the resource directly, not wrapped in a data object.

Pagination

Most collection endpoints accept:

Parameter	Type	Notes
cursor	string	Opaque cursor from the previous page
page_size	integer	Default 100, minimum 1, maximum 100

Behavior

• Missing cursor means the first page
• Invalid cursor returns 400 invalid_request
• Invalid page_size returns 400 invalid_request
• nextCursor is empty when there is no next page

Error envelope

Errors under /v1 use this shape:

{
  "code": "validation_failed",
  "message": "The issue write request was not valid.",
  "errors": [
    {
      "field": "title",
      "code": "required",
      "message": "A title is required."
    }
  ]
}

Field-level entries under errors vary by operation. The structure is stable even when the exact field codes differ.

Error codes

Code	Typical status	Meaning
unauthorized	401	Missing bearer token
invalid_token	401	Invalid or expired token
insufficient_scope	403	Missing required scope
forbidden	403	Authenticated caller cannot access the target resource
not_found	404	Resource not found or not visible
invalid_request	400	Invalid query or malformed request semantics
validation_failed	400	Invalid JSON payload
conflict	409	Request conflicts with existing data
rate_limited	429	API rate limit exceeded
internal_error	500	Unexpected server error

Rate limits

Surface	Default limit
/oauth	30 requests per 60 seconds
/v1	600 requests per 60 seconds

Rate-limited /v1 responses may include Retry-After.

Example:

{
  "code": "rate_limited",
  "message": "The rate limit has been exceeded. Retry after 12 seconds."
}

Plain text and rich text

• Issue and project description fields are plain text in the public API
• Issue and project write requests accept plain text description
• Issue comment write requests accept plain text body
• Issue comment responses return body as a structured rich-text document

Example rich-text comment body:

{
  "schemaVersion": 1,
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "First line"
          },
          {
            "type": "hardBreak"
          },
          {
            "type": "text",
            "text": "Second line"
          }
        ]
      }
    ]
  }
}

Redirect-based attachment access

Attachment content and preview endpoints do not return the file body directly. They return 302 Found redirects to signed URLs.

ID aliases in nested issue objects

Several nested issue objects expose both a specialized ID field and a generic id alias.

Example:

{
  "statusId": "iss-status_open",
  "id": "iss-status_open",
  "name": "Open"
}

This pattern applies to nested issue status, issue project, issue label, and issue link objects.

Dates and timestamps

• DateTimeOffset values are ISO 8601 timestamps such as 2025-02-24T16:45:00Z
• DateOnly values are YYYY-MM-DD

Enum codes

Several response fields serialize as numeric codes.

Priority

Value	Meaning
0	None
1	Urgent
2	High
3	Medium
4	Low

Member principal kind

Value	Meaning
0	Human
1	Service
2	Agent

Member role

Value	Meaning
1	Owner
2	Admin
3	Member
4	Guest

Member status

Value	Meaning
1	Invited
2	Active
3	Suspended
4	Removed

SCM provider

Value	Meaning
1	GitHub
2	Azure DevOps

Attachment preview kind

Value	Meaning
0	Unsupported
1	Image
2	Pdf
3	Video
4	Audio
5	Text
6	Code
7	Word
8	Excel

Agent message type

Value	Meaning
1	Automated
2	Journal
3	Update
4	Handover

Agent message author type

Value	Meaning
1	Human
2	Agent
3	System

Agent thread status

Value	Meaning
1	Active
2	WaitingOnAgent
3	WaitingOnUser
4	Closed