Skip to content

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:

QueryTypeDefaultDescription
pagenumber ≥ 11Page
pageSizenumber 1–10020*Items per page
searchstring–Full-text search (where supported)
sortstring–Sort field (where supported)

* pageSize defaults to 50 for Lists and List Items.

json
{
  "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 ​

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

Rate limiting ​

The REST API counts per minute in three buckets:

BucketLimit per minute
per user, all paths together100 requests
per user and path30 requests
per path, across all callers50 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 — read
  • POST — create
  • PATCH — partial update (only the fields you send are changed)
  • DELETE — delete (for Lists/Items: soft delete → trash)