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
The REST API counts per minute in three buckets:
| Bucket | Limit per minute |
|---|---|
| per user, all paths together | 100 requests |
| per user and path | 30 requests |
| per path, across all callers | 50 requests |
"Path" is the concrete path including IDs — /v1/lists/A and /v1/lists/B count separately. Without valid authentication, the IP address counts instead of the user.
Every response carries the current state in headers: X-RateLimit-UserLimit, X-RateLimit-UserRemaining, X-RateLimit-UserReset, and the same as X-RateLimit-UserPath* and X-RateLimit-Path*. A bucket without headers does not apply. When a limit is exceeded, the API answers 429 with Retry-After (seconds until the exhausted bucket is free again).
The MCP endpoint /api/mcp is counted separately with its own limit (240/min per user) — see Rate limits & errors.
Method semantics
GET— readPOST— createPATCH— partial update (only the fields you send are changed)DELETE— delete (for Lists/Items: soft delete → trash)