Skip to content

Table of contents

Using the HTTP API of cozy-stack

HTTP Codes

The developers of cozy-stack are trying to respect the semantics of HTTP, and the HTTP response code is symbolic of that. The stack uses a large range of HTTP codes, but the most common ones are:

  • 200 OK for a successful operation, with information in the HTTP body
  • 201 Created for a document successfully created
  • 204 No Content for a success with no relevant information to send (like a successful deletion)
  • 400 Bad Request when the request is incorrect
  • 401 Unauthorized when no authorization has been sent, or the token is expired
  • 402 Payment Required when the instance has been blocked and a user action is required (payment, or validating the Terms of Services)
  • 403 Forbidden when the authorization has been sent, is valid, but does not grant access to the resource
  • 404 Not Found when the resource is not found
  • 409 Conflict when there is a conflict on the managed resource
  • 410 Gone when a Cozy instance has been moved to a new address
  • 412 Precondition Failed when a parameter from the HTTP headers or query string is invalid
  • 422 Unprocessable entity when an attribute in the HTTP request body is invalid
  • 500 Internal Server Error when something went wrong on the server (bug, network issue, unavailable database)
  • 502 Bad Gateway when an HTTP service used by the stack is not available (apps registry, OIDC provider)



Except for the routes in /data, which imitate couchdb, most of the stack exposes a JSON-API interface.

See JSON-API specification for more information.


All routes that return a list are (or will be) paginated.

As recommended for couchdb, we use cursor-based pagination.

The default page limit is determined on a by-route basis. The client can require a different limit using page[limit] query parameter. If the client does not specify a limit, default limit will be used instead.

If there is more docs after the limit, the response will contain a next key in its links section, with a page[cursor] set to fetch docs starting after the last one from current request.

Alternatively, the client can opt in for skip mode by using page[skip]. When using skip, the number given in page[skip] is number of element ignored before returning value. Similarly, the response will contain a next link with a page[skip] set for next page (skip + limit).


The /relationships/references as a default limit of 100.

GET /data/some-type/some-id/relationships/references HTTP/1.1
    "data": ["... 100 docs ..."],
    "links": {
        "next": "/data/some-type/some-id/relationships/references?page[limit]=100&page[cursor]=7845122548848454212"
GET /data/some-type/some-id/relationships/references?page[limit]=10 HTTP/1.1
    "data": ["... 10 docs ..."],
    "links": {
        "next": "/data/some-type/some-id/relationships/references?page[limit]=10&page[cursor]=5487ba7596"
GET /data/some-type/some-id/relationships/references?page[limit]=100&page[cursor]=7845122548848454212 HTTP/1.1
    "data": ["... 20 docs ..."]
GET /data/some-type/some-id/relationships/references?page[limit]=10&page[skip]=0 HTTP/1.1
    "data": ["... 10 docs ..."],
    "links": {
        "next": "/data/some-type/some-id/relationships/references?page[limit]=10&page[skip]=10"