# JMAP for this API JMAP ([RFC 8620](https://www.rfc-editor.org/rfc/rfc8620)) is a JSON protocol over HTTPS: one session document, one API URL that takes a batch of method calls, and URLs for uploads, downloads and push. This chapter says as much of it as an application of this API needs; RFC 8620 says the rest. Files are the FileNode type of [draft-ietf-jmap-filenode](https://datatracker.ietf.org/doc/draft-ietf-jmap-filenode/) (revision 14); everything else is the install's own, under two capabilities. ## 1. The session `GET /.well-known/jmap` with the access token, following the redirect. The example shows the parts an application uses; the document holds more. ```http GET /jmap/session HTTP/1.1 Authorization: Bearer ${accessToken} ``` ```http HTTP/1.1 200 OK content-type: application/json; charset=utf-8 { "capabilities": { "urn:ietf:params:jmap:core": { "maxSizeUpload": 536870912, "maxConcurrentUpload": 16, "maxSizeRequest": 10000000, "maxConcurrentRequests": 48, "maxCallsInRequest": 16, "maxObjectsInGet": 500, "maxObjectsInSet": 500, "collationAlgorithms": [ "i;ascii-numeric", "i;ascii-casemap", "i;unicode-casemap" ] }, "urn:ietf:params:jmap:filenode": {}, "https://ns.ordner.fyi/svc/jmap/files": {}, "https://ns.ordner.fyi/svc/jmap/photos": {} }, "accounts": { "${accountId}": { "name": "pip@ordner.example", "isPersonal": true, "isReadOnly": false, "accountCapabilities": { "urn:ietf:params:jmap:filenode": { "maxFileNodeDepth": 256, "maxSizeFileNodeName": 255, "mayCreateTopLevelFileNode": false }, "https://ns.ordner.fyi/svc/jmap/photos": { "mayRender": false } } } }, "primaryAccounts": { "urn:ietf:params:jmap:filenode": "${accountId}", "https://ns.ordner.fyi/svc/jmap/photos": "${accountId}", "urn:ietf:params:jmap:blob": "${accountId}", "urn:ietf:params:jmap:quota": "${accountId}" }, "username": "pip@ordner.example", "apiUrl": "${apiUrl}", "downloadUrl": "${downloadUrl}", "uploadUrl": "${uploadUrl}", "eventSourceUrl": "${eventSourceUrl}", "state": "${*}" } ``` - **`capabilities`** lists what the install offers. This API is `urn:ietf:params:jmap:core`, `urn:ietf:params:jmap:filenode` (FileNode), `https://ns.ordner.fyi/svc/jmap/files` (annotations, fields, views, vectors, sources, facets) and `https://ns.ordner.fyi/svc/jmap/photos` (the `photo` value, faces, people, album suggestions). Their values are `{}` today. `urn:ietf:params:jmap:blob` and `urn:ietf:params:jmap:quota` are there too when the install hosts blobs. - **`accounts`** are the drives the credential reaches: the person's own (`isPersonal: true`) and each drive delegated to them. `isReadOnly` is `false` where the credential may write anything there, annotations included. Each account's `accountCapabilities` say what it supports; `mayCreateTopLevelFileNode` is `true` only with `drive:write`. - **`primaryAccounts["urn:ietf:params:jmap:filenode"]`** is the person's own drive. - **`apiUrl`, `uploadUrl`, `downloadUrl`, `eventSourceUrl`** are absolute URLs on the install (RFC 6570 level-1 templates): `…/jmap/api`, `…/jmap/upload/{accountId}`, `…/jmap/download/{accountId}/{blobId}/{name}?type={type}`, `…/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}`. (The examples run against the files service directly, which answers them relative.) - **`state`** changes when the session does (a delegation accepted, a capability added): every API answer carries `sessionState`; when it differs from the session's, fetch the session again. ## 2. A request `POST` to `apiUrl` with `Content-Type: application/json`: ```json { "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:filenode", "https://ns.ordner.fyi/svc/jmap/files"], "methodCalls": [ ["FileNode/query", { "accountId": "…", "filter": { "isAnnotated": false } }, "q"], ["FileNode/get", { "accountId": "…", "#ids": { "resultOf": "q", "name": "FileNode/query", "path": "/ids" } }, "g"] ] } ``` - `using` names every capability whose methods the request calls. A method of a capability not named is `unknownMethod`. - Each call is `[name, arguments, callId]`; the answer holds one or more `[name, arguments, callId]` per call, in order, with the same `callId`. A method that fails answers `["error", { "type", "description" }, callId]` and the others still run. - A **back-reference** (`"#ids": { "resultOf", "name", "path" }`) takes an argument from an earlier answer in the same request (RFC 8620 §3.7): a query and the reading of what it found are one round trip. - At most `maxCallsInRequest` calls per request; at most `maxObjectsInGet` ids per `/get` and `maxObjectsInSet` objects per `/set` unless the method says less (§5). ## 3. The standard methods Every type of this API follows RFC 8620 §5 where it has the method: | Method | Arguments | Answer | |---|---|---| | `T/get` | `accountId`, `ids` (or `null`: all, where allowed), `properties` | `state`, `list`, `notFound` | | `T/changes` | `accountId`, `sinceState`, `maxChanges` | `oldState`, `newState`, `hasMoreChanges`, `created`, `updated`, `destroyed` | | `T/set` | `accountId`, `ifInState`, `create`, `update`, `destroy` | `oldState`, `newState`, `created`, `updated`, `destroyed`, `notCreated`, `notUpdated`, `notDestroyed` | | `T/query` | `accountId`, `filter`, `sort`, `position` or `anchor` and `anchorOffset`, `limit`, `calculateTotal` | `queryState`, `canCalculateChanges`, `position`, `ids`, `total`, `limit` | | `T/queryChanges` | `accountId`, `sinceQueryState`, … | `added`, `removed` | - A `/set` that refuses one object answers a **SetError** for it in `notCreated`, `notUpdated` or `notDestroyed` (`{ type, description, properties }`); the rest are written. An `update` answer is `null` or the server-set values that changed. - `/changes` answers `cannotCalculateChanges` when it can no longer say what changed since that state; the application then reads again ([Keeping up](keeping-up.md) §3). - A `/query` window is RFC 8620 §5.5's: a negative `position` counts from the end, an `anchor` replaces the position and `anchorOffset` may be negative, a page past the end is empty, and a malformed argument is `invalidArguments`. Where the server caps a page or sets its size when the request gives none, it answers that as `limit`. - A `maxChanges` that is not a positive integer is `invalidArguments`, even where nothing changed. - States are opaque strings: compare them for equality, never order them. ## 4. Upload, download and push **Upload** (RFC 8620 §6.1): `POST` the bytes to `uploadUrl` with their `Content-Type`. The answer is `201` with `{ accountId, blobId, type, size }`. The blob id is used in a `/set` (a file's content, an annotation's text) within the same session; an upload nobody uses is removed later. ```http POST /jmap/upload/${accountId} HTTP/1.1 Authorization: Bearer ${accessToken} Content-Type: text/plain; charset=utf-8 INVOICE Hansen Boat Yard Hull cleaning and antifouling Total 249.90 EUR, due 15 November 2026 ``` ```http HTTP/1.1 201 Created content-type: application/json; charset=utf-8 { "accountId": "${accountId}", "blobId": "${invoiceText}", "type": "text/plain; charset=utf-8", "size": 93 } ``` **Download** (RFC 8620 §6.2): `GET` `downloadUrl` with `accountId`, `blobId`, a file `name` and the `type` to answer with. The answer is the bytes, as an attachment, with `X-Content-Type-Options: nosniff`; a script type is answered as `application/octet-stream`. One byte range is served (`206`), so a large file can be read in parts or resumed. A file's content blob id (`FileNode.blobId`) is bound to the person who read it: download it with a credential of the same person. ```http GET /jmap/download/${accountId}/${invoiceTextBlobId}/invoice.txt?type=text/plain HTTP/1.1 Authorization: Bearer ${accessToken} ``` ```http HTTP/1.1 200 OK content-type: text/plain content-disposition: attachment; filename="invoice.txt"; filename*=UTF-8''invoice.txt INVOICE Hansen Boat Yard Hull cleaning and antifouling Total 249.90 EUR, due 15 November 2026 ``` **Push** (RFC 8620 §7.3): `GET` `eventSourceUrl` with `types` (comma separated, or `*`), `closeafter` (`state` or `no`) and `ping` (seconds, held to 30–300; `0` for none), with the same `Authorization` header. The stream answers `text/event-stream`; each `state` event's data is a `StateChange`: per account, the types whose state moved. See [Keeping up](keeping-up.md) §5. ## 5. Capabilities and limits | Limit | Value | Where | |---|---|---| | `maxCallsInRequest` | 16 | session (core) | | `maxObjectsInGet` | 500 | session (core); `FileNode/get` and `/query` hold to it | | `maxObjectsInSet` | 500 | session (core); methods below say less | | `maxSizeRequest` | 10,000,000 bytes | session (core) | | `maxConcurrentRequests` | 48 per person | session (core) | | `maxSizeUpload` | 536,870,912 bytes (files); the session answers the lowest of the install's services | session (core) | | `maxConcurrentUpload` | 16 | session (core) | | EventSource streams | a few per credential; more is `429` | — | | `FileAnnotation/set` | 256 updates and destroys per call | — | | `FileVector/set` | 256 per call; 4 vectors per file per source | — | | `FileVector/get` | 500 ids | — | | `AnnotationView/set` | 64 per call; 50 views per source | — | | `AlbumSuggestion/set` | 256 per call; 200 pending per source | — | | `AlbumSuggestion/get` | 500 ids | — | | `PhotoFace/get` | 500 ids | — | | `PhotoPeople/set` | 500 pictures per call | — | | `PhotoFace/set` | 1,000 embeddings per call | — | | `AppData/destroy` | 256 annotations per call | — | | `FileNode/facets` | 10 facets, 100 values each | — | **Read the core limits from the session** rather than from this table: the session answers the lowest value among the install's services, and an install may lower them. The per-method limits are the server's constants; the [Reference](reference.md) gives every other one (lengths, counts, dimensions), and the [JSON Schema](schema/) carries them too.