Skip to content
Start free

Quickstart

Your first call

A token, one request, and the envelope everything comes back in. Nothing here needs an agent, a webhook or a connected account — a token and a terminal is the whole setup.

Base path
/api/v1
Auth
Bearer token
Format
JSON
Version header
X-Xyranik-Api-Version

1. Make a token

Tokens are created in Settings, with only the scopes they need. The value is shown once and never again — only a one-way hash is kept, so a token that is lost is replaced rather than recovered.

  • xyr_live_…
    Reads and writes this workspace’s records.
  • xyr_test_…
    Reads this workspace’s real records and never writes. A write is checked exactly as a live one would be and answered with simulated: true, and nothing is recorded. The order and identity routes, which can only write for real, refuse it.

Start with a xyr_test_ token. It reads your real records and simulates every write, so you can run the whole integration against real data before anything can change.

2. Send a request

GET /api/v1/missionsExample
curl "$XYRANIK_HOST/api/v1/missions" \
  -H "Authorization: Bearer xyr_live_…"

$XYRANIK_HOST is your own Xyranik address. Every request is a bearer token over HTTPS.

Everything comes back in one envelope. data is the answer; meta appears only when there is more to say, such as another page — it is left out rather than sent empty.

200 OKExample
{
  "data": [
    {
      "id": "…",
      "goal": "More repeat customers this quarter",
      "status": "active"
    }
  ]
}

Fields vary by endpoint. The shape of the envelope does not.

3. Page through a list

Lists take limit — at most 100 — and return meta.nextCursor when there is another page. Send it back as cursor. A cursor this API did not issue is refused rather than interpreted.

Next pageExample
curl "$XYRANIK_HOST/api/v1/decisions?limit=100&cursor=…" \
  -H "Authorization: Bearer xyr_live_…"

4. Read the headers

  • X-Xyranik-Api-Version
    The API version that answered. Always present.
  • X-Xyranik-Mode
    Whether a live or a test credential asked.
  • X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After
    What is left of the allowance, when it resets, and how long to wait after a 429.
  • Idempotency-Key
    Send one on a write and a repeat is answered with the first result rather than acted on twice, for 24 hours.
  • Idempotent-Replayed
    Set when the answer you are reading is a replay of an earlier identical request.

What to read next

  • Authentication
    Every scope, what it opens, and which three reach people outside the workspace.
  • Errors and limits
    What it answers when it refuses, and which refusals are worth retrying.