JMAP for this API #
JMAP (RFC 8620) 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 (revision 14); everything else is the install's own, under two capabilities.
1. The session #
GET <origin>/.well-known/jmap with the access token, following the
redirect. The example shows the parts an application uses; the document
holds more.
GET /jmap/session HTTP/1.1
Authorization: Bearer ${accessToken}
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": "${*}"
}
capabilitieslists what the install offers. This API isurn:ietf:params:jmap:core,urn:ietf:params:jmap:filenode(FileNode),https://ns.ordner.fyi/svc/jmap/files(annotations, fields, views, vectors, sources, facets) andhttps://ns.ordner.fyi/svc/jmap/photos(thephotovalue, faces, people, album suggestions). Their values are{}today.urn:ietf:params:jmap:blobandurn:ietf:params:jmap:quotaare there too when the install hosts blobs.accountsare the drives the credential reaches: the person's own (isPersonal: true) and each drive delegated to them.isReadOnlyisfalsewhere the credential may write anything there, annotations included. Each account'saccountCapabilitiessay what it supports;mayCreateTopLevelFileNodeistrueonly withdrive:write.primaryAccounts["urn:ietf:params:jmap:filenode"]is the person's own drive.apiUrl,uploadUrl,downloadUrl,eventSourceUrlare 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.)statechanges when the session does (a delegation accepted, a capability added): every API answer carriessessionState; when it differs from the session's, fetch the session again.
2. A request #
POST to apiUrl with Content-Type: application/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"]
]
}
usingnames every capability whose methods the request calls. A method of a capability not named isunknownMethod.- Each call is
[name, arguments, callId]; the answer holds one or more[name, arguments, callId]per call, in order, with the samecallId. 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
maxCallsInRequestcalls per request; at mostmaxObjectsInGetids per/getandmaxObjectsInSetobjects per/setunless 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
/setthat refuses one object answers a SetError for it innotCreated,notUpdatedornotDestroyed({ type, description, properties }); the rest are written. Anupdateanswer isnullor the server-set values that changed. /changesanswerscannotCalculateChangeswhen it can no longer say what changed since that state; the application then reads again (Keeping up §3).- A
/querywindow is RFC 8620 §5.5's: a negativepositioncounts from the end, ananchorreplaces the position andanchorOffsetmay be negative, a page past the end is empty, and a malformed argument isinvalidArguments. Where the server caps a page or sets its size when the request gives none, it answers that aslimit. - A
maxChangesthat is not a positive integer isinvalidArguments, 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.
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/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.
GET /jmap/download/${accountId}/${invoiceTextBlobId}/invoice.txt?type=text/plain HTTP/1.1
Authorization: Bearer ${accessToken}
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 §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 gives every other one (lengths, counts, dimensions), and the JSON Schema carries them too.