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:

* pageSize defaults to 50 for Lists and List Items.

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

HTTP status codes ​

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)