Conventions

Format

• Requests & responses: application/json.
• IDs: UUID or SID (short ID) are accepted for most resources.
• Timestamps: ISO 8601 (UTC).

Authentication

Bearer token in the Authorization header. Without a valid token → 401.

Pagination

List endpoints accept page and pageSize (not limit/offset) and return an envelope with a pagination object:

Query	Type	Default	Description
page	number ≥ 1	1	Page
pageSize	number 1–100	20*	Items per page
search	string	–	Full-text search (where supported)
sort	string	–	Sort field (where supported)

* pageSize defaults to 50 for Lists and List Items.

{
  "data": [ … ],
  "pagination": { "total": 128, "page": 1, "pageSize": 50, "totalPages": 3 }
}

To fetch the next page, increase page until page >= totalPages.

Difference from MCP

The MCP server uses a different schema: limit/offset as input and { items, total, limit, offset, has_more } as the response. The REST API uses page/pageSize and the pagination envelope above.

HTTP status codes

Code	Meaning
200	OK
201	Created
400	Bad request (validation)
401	Not authenticated
403	Not authorized
404	Not found
429	Rate limit exceeded (see below)

Rate limiting

As with the MCP endpoint: 240 requests/minute per token. When exceeded, a 429 is returned with a Retry-After header.

Method semantics

• GET — read
• POST — create
• PATCH — partial update (only the fields you send are changed)
• DELETE — delete (for Lists/Items: soft delete → trash)