Call the API
Success is the resource. Failure is a problem document. One call names one drive.
server is api.contextdrive.io. HTTP and MCP call the same actions. The gateways do not decide policy on their own. Drive calls this same API. File bytes do not pass through Drive or through the request body.
JSON names are camelCase. Timestamps are ISO-8601. Enum values are the lowercase names stored in the database. Product ids are UUID v7.
Success and failure
A success body is the resource. 200 returns it. 201 returns the created resource and a Location header. 204 has no body. A list is { "items", "limit", "offset", "total" }. A query result stays a query result. There is no envelope around a single resource.
A failure is application/problem+json (RFC 9457). The body carries type, title, status, detail, and instance. type is https://contextdrive.io/problems/{slug}. Field failures add errors. Each entry is {field}: {message}.
| Status | Slug | When |
|---|---|---|
| 400 | bad-request | The body or a query parameter is invalid, or the caller does not hold the tag. |
| 404 | not-found | The object is not visible to this caller. The detail does not say whether the id exists. |
| 409 | conflict | The email, the name, or another unique value is already used. |
| 503 | unavailable | Storage is not available, or the model is not configured on a draft. |
| 500 | internal | The request failed. |
Lists
limit and offset are query parameters on every list, including a PUT that returns the list it replaced, and on search. An absent limit returns every visible row, and the response limit equals total. An absent offset is 0. limit below 1, offset below 0, and limit above 100 are 400. The maximum is not clamped. Hidden rows are omitted and do not count.
Directory and file lists also take sort (name, kind, size, or modified, default name) and direction (asc or desc, default asc). A tie breaks on id, and that tie-break stays ascending. Size is byteSize. Modified is createdAt. A directory has no byte size, so a size sort ties.
Search keeps its hit cap. limit and offset window that capped set, and total is the size of the capped set.
A note list is oldest first, by createdAt and then id. limit and offset window it.
The caller
A credential is one user. The organization is that user’s organization. A named organization id must match it. A client body cannot set the organization, the user, or the drive as an owner of the row. The path names the drive.
Sign-in tokens are the production credential. server will verify the token and map the subject to its user row. That verification is not on yet. In production mode, /v1 is refused until it lands, except POST /v1/organizations.
On a development server, when auth mode is dev, send X-Dev-User-Id with a user id. The header is ignored when the mode is jwt. POST /v1/organizations does not read it. That call creates the organization and the owner.
Where the routes are
HTTP is the route list. SQL is how a statement names the tables. MCP is the same work as tools. ctx is the client on the caller’s machine.
In this section