Skip to content
Sursa Developers

Time and formats

JSON and text

  • Request and response bodies are JSON in UTF-8, with Content-Type: application/json. File uploads use multipart/form-data.
  • Field names and enum values are snake_case: next_retry_at, index_failed.
  • Error messages and the texts of the API are in English. Texts you write, such as card titles, are returned as you wrote them, in any language.

Times

Every time is an RFC 3339 timestamp in UTC:

{"created_at": "2026-10-24T10:00:00Z"}
  • Newer fields use the short form with Z, as above.
  • Some fields that existed earlier use the form 2026-10-24T10:00:00.123456+00:00, with up to six digits of fractions of a second. It is the same moment in UTC. Parse both forms with a standard RFC 3339 parser; do not compare timestamps as strings.
  • Every field whose name ends in _at is a timestamp.

Times you send must include a time zone offset, either Z or a numeric offset such as +02:00. A time without an offset is ambiguous and returns 422 with the code validation.failed. Sursa converts every time it receives to UTC.

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

In a query string, a + must be written as %2B, or it is read as a space. URL-encode time values, or use Z.

Dates, durations and counts

KindFormExample
Date without a timeYYYY-MM-DD, in a field ending in _date"due_date": "2026-11-01"
DurationAn integer, with the unit in the field name"interval_days": 90, "timeout_seconds": 30
CountAn integer, in a field ending in _count"part_count": 12
True or falseA boolean, named by an adjective without is_"active": true, "sensitive": false

Amounts of money

Amounts in financial responses are decimal strings, such as "1250.00", never floating-point numbers, so that no precision is lost. The currency is a separate field with an ISO 4217 code, such as "EUR". Parse amounts with a decimal type in your language.

IDs

IDs are strings or integers depending on the object. See Object IDs.

Enumerations

Fields with a fixed set of values, such as a status, are strings. Every enumeration in a response can get new values in a later version: treat a value you do not know as "other". See Versions and compatibility.

Null and missing fields

  • null means "no value": a card without an owner has "owner_id": null.
  • A field can be missing from a response when it does not apply to this object or this request. The API reference marks which fields are always present.
  • In a PATCH, a field you leave out keeps its value. Send null to clear a field where the reference says that null is allowed.