Skip to content
Start free

API v1

Build on Xyranik

Two ways in. A workspace token reads and writes your growth record over a plain JSON API. An agent credential asks one question — may this agent do this, here, now? — and is answered by the same gateway that judges Xyranik’s own agents.

Version
v1
Base path
/api/v1
Rate limit
600/1h per token
Page size
100 max

Two credentials, and they are not interchangeable

Which one you hold decides what you are asking. A workspace token acts as the workspace and carries the scopes you gave it. An agent credential stands for one agent and carries no scopes at all, because what that agent may do is not a property of the key — it is decided for every request.

  • xyr_live_…
    A workspace token. Scoped, revocable, and stored only as a one-way hash. A leaked one is the workspace, which is why the scopes matter and why rotation has an overlap.
  • xyr_agt_…
    An agent credential, issued in Agent controls. It stands for one agent. Revoking it stops that agent and nothing else. 1200 requests an hour, per credential.

Registering an agent and issuing it a credential are deliberately not things a token can do. Widening what may act in a workspace stays with a person, in Agent controls — a leaked token that could mint agent identities would be worse than anything the convenience is worth.

The call the platform is for

Your agent describes what it wants to do. Xyranik answers against the workspace’s permissions, the data the action would use, how risky the request is, and the rules the owner wrote in their own words. The model asking never decides, and every answer is written down — refusals included.

POST /api/v1/agent/authorizeExample
curl -X POST "$XYRANIK_HOST/api/v1/agent/authorize" \
  -H "Authorization: Bearer xyr_agt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "ads",
    "action": "increase_budget",
    "resource": "Spring campaign",
    "facts": { "amountPercent": 35, "increase": true }
  }'

$XYRANIK_HOST is your own Xyranik address. Facts are what the risk and the workspace’s rules are judged against.

The answer names the verdict, and says plainly whether to go ahead:

  • allowed
    Go ahead. `mayProceed` is true.
  • requires_approval
    A person in the workspace has to decide first. This is not a yes.
  • denied
    No, with the reason and the check that refused it.

Branch on carriedOutBy, not on the status code. Where the workspace has registered its own endpoint for a tool, Xyranik carries the action out itself and mayProceed is false even when the verdict is allowed. An agent that read any 200 as permission would do the work twice.

What you can read back

The same API reads the record the product is built on: the decisions with the predictions written before the outcome, the missions and what they are measured against, the signals and opportunities, the experiments and what each test said, and the revenue traced back to what caused it — or plainly marked untraceable, which is the answer more often than a dashboard would admit.

  • Growth record
    Missions, decisions, signals, opportunities, experiments, outcomes.
  • People and revenue
    Contacts, customers, orders and what the money is attributed to.
  • Agents
    The agents in the workspace, the tools they may use, and the rules that govern them.
  • Your own usage
    What each token has been doing, counted where each call was answered.

The full list, with the scope each one needs, is on the API reference. It is also served by the API itself, so it cannot describe an endpoint that is not there.

Where to start

  • Quickstart
    Make a token, send one call, and read what comes back.
  • Authentication
    The scopes, the two modes, and how a token is replaced without an outage.
  • Authorisation
    What the gateway checks before it answers, and why it fails closed.