API Request and Response format

February 5, 2026 at 2:53 PM Edit on Gitlab

Request and Response format

Table of Contents

Notice: The format described here is not implemented in all our APIs. Some API versions (like Observation V1 to V4) could differ partially or fully from this document. Please consult our API Documentation to be sure.

Response status code

The HTTP response status code is the first description of the response content.

Response content type

You can expect several response content types. It could be either empty or an object but NEVER an array. When a json object is returned, the response data is available in a data property.

Empty response

Mainly for HTTP status code 204

Example:

An endpoint that return the difference between two arrays

// Request with arrays [1,2,3] and [1,2,3] will have a response with HTTP
// Status code: 204 No Content

// Request with arrays [1,2,3] and [1] will have a response with HTTP Status
// code: 200 OK
{
  "data": {
    "differences": [2, 3]
  }
}

Created response

Mainly for HTTP status code 201. Created responses of POST requests are returning an empty payload and a Location header containing the endpoint to call for retrieving the newly created content as specified in RFC 7231 « HTTP/1.1 Semantics and Content ».

Simple object response

Mainly for HTTP status code in the 2XX range

  • data: Response data
// Requested user will be sent with HTTP Status code: 200 OK
{
  "data": {
    "id": 4561385,
    "username": "john.doe",
    "email": "john.doe@mail.com",
    "firstname": "John",
    "lastname": "Doe",
    "country": "Switzerland",
    "preferred_lang": "fr-CH"
  }
}

List of objects

Sorting

When requesting list of objects, sorting is possible by using query parameters.

Note: Keep in mind that not all fields are allowed for sorting, the allowed fields are listed on the API Documentation.

The query parameter validation is applying those rules.

  • It is possible to use either the simple of complete sort format (simple is sort=id and complete is sort[id]=asc)
  • When a simple sort format is used the asc order is assumed
  • It is not possible to use both simple and complete sort format (sort=id and sort[date]=asc will return error 400)

So a sort could typically take the following form:

  • sort=id or sort[id]=asc: sort by ascending id
  • sort[id]=desc: sort by descending id
  • sort=date,quantity,id: sort by ascending date, then by ascending quantity, then by ascending id
  • sort[date]=desc&sort[quantity]=asc&sort[id]=asc: sort by descending date, then by ascending quantity, then by ascending id

Simple lists of objects

Mainly for HTTP status code in the 2XX range. By default all lists are returned without totals.

  • data: List of items
// Requested first names will be sent with HTTP Status code: 200 OK
{
  "data": [
    "Alice",
    "Bob",
    "Charlie",
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total response header.

X-Total: 400

Paginated list of object

Mainly for HTTP status code in the 2XX range. Pagination is triggered by using offset and/or limit query parameters. By default all lists are returned without totals or paging details.

  • data: List of items in the page
// Requested page of 2 first names will be sent with HTTP Status code: 200 OK
{
  "data": [
    "Alice",
    "Bob"
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total response header.

X-Total: 400

To have the pagination links returned, you need to add the query parameter with_paging=true. The paging will then be set in the Link response header.

Link: <https://endpoint_url?offset=40&limit=20>;rel="prev", <https://endpoint_url?offset=80&limit=20>;rel="next", <https://endpoint_url?offset=0&limit=20>;rel="first", <https://endpoint_url?offset=380&limit=20>;rel="last"

Filtered list of object

Mainly for HTTP status code in the 2XX range. Filtering is triggered by using one or more filter query parameters. By default all lists are returned without totals.

  • data: List of filtered items
// Requested first names containing the string `John` will be sent with HTTP
// Status code: 200 OK
{
  "data": [
    "John",
    "Johnathan"
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total and X-Filtered-Total response headers.

X-Filtered-Total: 27
X-Total: 400

Operators

You can filter a list of object by using query parameters. There is many supported operators.

Note: Keep in mind that not all operations are allowed on all fields depending on the API or endpoint, the allowed operations are listed on the API Documentation.

Filters are generally applied additionally (filter1 and filter2 and filter3) unless described otherwise in the API Documentation.

Equal operators
  • eq: the value is equal to
  • neq: the value is NOT equal to

Equal operator eq is the default operator. It is possible to use either the simple of complete filter format (simple is id=123 and complete is id[eq]=123).

Note: It is not possible to use both simple and complete filter format for a same field (id=123 and id[eq]=213 will return error 400)

Here are some examples:

  • country=Switzerland or country[eq]=Switzerland: country is Switzerland
  • status[neq]=active: any status other than active
Nullable operators
  • is_null: the value is NULL
  • is_not_null: the value is NOT NULL

Nullable operators do not need values but, two formats are allowed:

  • Operator only field[is_null]
  • true boolean value field[is_null]=true

Note: false boolean as value will throw an error so you need to use field[is_not_null]=true instead of field[is_null]=false

Here are some examples:

  • owner[is_null] or owner[is_null]=true: owner is NULL
  • end_date[is_not_null]: has an end date
Comparative operators
  • gt: the value is greater than
  • gte: the value is greater than or equal to
  • lt: the value is less than
  • lte: the value is less than or equal to

Here are some examples:

  • id[gt]=100: id is greater than 100
  • id[gte]=100&id[lt]=200: id is between 100 and 199
  • date[gte]=2023-01-01&date[lt]=2024-01-01: date is in 2023
Set operators
  • in: the value is included in
  • not_in: the value is NOT included in

Set operators expect an array as value and support multiple formats:

  • Implicit array separated by tilde ~ character field[in]=one~two~three
  • Implicit array separated by comma , character field[in]=one,two,three. If a tilde ~ character is found, it will be used as implicit separator and the comma , will be considered as part of the value
  • Explicit array field[in][]=one&field[in][]=two&field[in][]=three. When explicit array is used, both tilde ~ and comma , separators will be ignored and considered part of the value.

Note: It is not possible to use both implicit and explicit array format for a same field (tag[in]=red,blue and tag[in][]=yellow will return error 400)

Here are some examples:

  • tag[in]=news,offer: offer and news tagged content
  • type[in]=river,forest&canton[not_in][]=GE&canton[not_in][]=ZH: rivers and forest in any canton other that Geneva and Zurich
Search operators
  • starts_with: the value starts with
  • contains: the value contains
  • ends_with: the value ends with

Here are some examples:

  • name[starts_with]=J&name[ends_with]=n: names like John or Juan
  • description[contains]=flower: descriptions that contain the word “flower”
Case insensitive operators
  • i_eq: the value is equal to
  • i_neq: the value is NOT equal to
  • i_starts_with: the value starts with
  • i_contains: the value contains
  • i_ends_with: the value ends with

Here are some examples:

  • name[i_eq]=john: names matching “john”, “John”, “JOHN”, etc.
  • description[i_contains]=flower: descriptions containing the word “flower”, “Flower”, “FLOWER”, etc. regardless of case
Wildcard operators
  • w_eq: the value is equal to
  • w_neq: the value is NOT equal to
  • w_starts_with: the value starts with
  • w_contains: the value contains
  • w_ends_with: the value ends with

When using an operation with wildcard support (beginning with w_ or iw_) the following character are considered a wildcard:

  • ? Only one character
  • * One or more characters

Here are some examples:

  • name[w_eq]=j?hn: names exactly matching “john”, “jahn”, “j0hn”, etc.
  • filename[w_contains]=data*.csv: filenames containing strings like “data.csv”, “data_export.csv”, “data-2023.csv”, etc.
  • species[w_starts_with]=pin*: species starting with “pin” followed by any characters, like “pinus”, “pinguicula”, etc.
Case insensitive & wildcard operators
  • iw_eq: the value is equal to
  • iw_neq: the value is NOT equal to
  • iw_starts_with: the value starts with
  • iw_contains: the value contains
  • iw_ends_with: the value ends with

See Wildcard operators for details on the wildcard characters.

Field types and possible operators

Here are the operations possible on each field type:

Operation boolean date number string
is_null x x x x
is_not_null x x x x
eq x x x x
neq x x x x
gt x x
gte x x
lt x x
lte x x
in x x
not_in x x
starts_with x
contains x
ends_with x
i_eq x
i_neq x
i_starts_with x
i_contains x
i_ends_with x
w_eq x
w_neq x
w_starts_with x
w_contains x
w_ends_with x
iw_eq x
iw_neq x
iw_starts_with x
iw_contains x
iw_ends_with x

Totals and paging links without data

Since the generation of totals might significantly impact the response time of your request you can request the totals separately by doing a HEAD request with the exact same parameters you are using in your GET request. Don’t forget to set the with_total=true and/or with_paging=true to have que needed information.

Errors

Mainly for HTTP status code in the 4XX range

  • error: Error name (machine readable)
  • error_description: Human readable message that could be presented to the user
  • data (optional): additional data about the error
// The catched AlreadyExistError will be forwarded with HTTP Status
// code: 409 Conflict
{
  "error": "already_exists_error",
  "error_description": "There is already a User with this username in the database",
  "data": {
    "username": "john.doe",
  }
}

// The catched TokenExpiredError will be forwarded with HTTP Status
// code: 401 Unauthorized
{
  "error": "token_expired_error",
  "error_description": "Token is expired"
}

if an error code is provided it should be an application-scoped error code and not the HTTP Status code replication

// The code 4503 could allow the developer to pinpoint exactly the piece of
// code that generated the error if there is multiple possible occurrences of
// this error. It can also be a id referencing an error occurrence in an error
// tracking tool.
{
  "error": "forbidden_error",
  "code": 4503,
  "error_description": "Edit is not authorized on archived item"
}