How the Slen API works

The base address, the shape of a request and of an answer, and the conventions every operation of the API follows.

4 min read

The Slen API is an HTTP API that speaks JSON. Every operation follows the same few conventions. This page states them once, and the page of each resource relies on them.

Base address and version

Every path of this reference is relative to one base address.

Base address

https://api.slen.ai/api

The paths of the API start with /v1. The version is part of the path, and this reference describes version 1. Two probes, /health and /ready, stand outside /v1 and take no key.

A request

A request carries an API key in the Authorization header — Authentication says how. Where an operation takes a body, the body is JSON, sent with Content-Type: application/json.

Terminal

curl https://api.slen.ai/api/v1/models \
  -H "Authorization: Bearer $SLEN_API_KEY"

200 OK

{
  "data": [
    {
      "model_code": "gpt-4o-mini",
      "provider": "openai",
      "model_price_id": "1108",
      "input_price_per_million": "0.15000000",
      "output_price_per_million": "0.60000000",
      "cached_input_price_per_million": "0.07500000",
      "max_output_tokens": 16384,
      "currency": "USD",
      "effective_from": "2026-01-01T00:00:00+00:00",
      "effective_to": null
    }
  ]
}

The request that runs a flow and the operations that move a customer's credits — a top-up, a charge, an adjustment — also require an Idempotency-Key header. It is a key of your own that names one piece of work, so a new piece of work gets a new key. The page of a resource marks the operations that require it.

A successful answer

A successful answer is JSON with the payload inside data — an object for one thing, an array for a list.

A list that is read page by page adds meta. Take meta.next_cursor from one page and send it as the cursor parameter of the next request. On the last page it is null.

Two kinds of answer are not wrapped in data:

an answer with the status 204 has no body;
the two probes answer with a plain object;

Errors

A request that is refused or fails answers with a status of the 4xx or 5xx family. An error the API reports itself comes in one envelope.

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is missing or invalid",
    "request_id": "3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10"
  }
}

Field	What it carries
`error.code`	The stable name of what happened. Branch on it, never on the text.
`error.message`	An explanation for a person. Its wording may change.
`error.details`	An object with more, where the code carries structure. Absent otherwise.
`error.request_id`	The id of the request, the same as the `X-Request-Id` header of the answer.

Every code is listed on Error codes, with what it means and what to do about it.

A 422 comes in two shapes. A request the product refuses answers with the envelope above. A field that fails validation — a missing name, a number where a string is expected — answers with message and errors, a map of a field's name to the list of what is wrong with it.

A few other answers come without the envelope too: a 404 for a path the API does not have, a 405 for a method a path does not take, a 500 for a failure the API did not expect. Such an answer has message and no error. When an answer has no error, branch on its status.

How values are written

Value	How it is written
Field names	`snake_case`, in a request and in an answer
Money	A decimal string, never a number. An answer carries eight digits after the point, as in `"0.02700000"`
Credits	A decimal string with four digits after the point, as in `"12.5000"`
Shares, rates and ratios	A decimal string, never a number, with as many digits after the point as its field says, as in `"0.7500"`. The field also says whether it is a fraction of 1 or a percent
Identifiers	A string of digits, as in `"74438200973594624"`. An id is too long for a number of JavaScript
Time	ISO 8601 with an offset, as in `"2026-10-02T08:41:00+00:00"`

Keep money and identifiers as strings on your side too. A value read into a floating-point number loses digits.

The id of a request

Every answer carries an X-Request-Id header, whether the request succeeded or not. Quote it when you write to support.

You may send an id of your own in the same header. An id of 8 to 128 characters — letters, digits, ., _, : and - — is kept and returned. Anything else is replaced with a new one.

Where to go next

Authentication — the key, the project it belongs to and the scopes.
Glossary — what an operation, a flow and a reservation are.