Reference · v1

API reference

Generated from the same declaration the routes are served from, so it cannot name an endpoint that is not there. The live version is served by the API itself, and the OpenAPI description beside it.

Base path: /api/v1
OpenAPI: /api/v1/openapi.json
Page size: 100 max
Rate limit: 600/1h

The same list as a file, for tools that generate a client from one: download the OpenAPI description (JSON).

The envelope

Every answer carries data. meta is present only when there is something to say — another page, usually — and omitted otherwise rather than sent as null. A refusal replaces both with error, carrying a code and a message.

ShapeExample

{ "data": … }                          // an answer
{ "data": [ … ], "meta": { "nextCursor": "…" } }   // a page of a list
{ "error": { "code": "forbidden", "message": "…" } }  // a refusal

Opened by a workspace token

Each one needs exactly the scope named beside it. A token without it is refused, and the message says which scope was missing.

EndpointScopeWhat it answers

GET/api/v1/decisions
read:growth
The decision ledger: each decision with its prediction and, once measured, what happened. Newest first.
GET/api/v1/missions
read:growth
Growth missions, each with its measured progress and the automations working on it.
GET/api/v1/signals
read:growth
What the product noticed in the business, and which opportunity each notice speaks for.
GET/api/v1/opportunities
read:growth
Things worth doing, in the order they are worth doing them, with the measured impact where there is one.
GET/api/v1/experiments
read:growth
Hypotheses written down before their tests were decided, and what each test said.
POST/api/v1/experiments
write:experiments
Write down a hypothesis against an email A/B test or a send with a held-back group, before it is decided.
GET/api/v1/outcomes
read:growth
How the predictions have held up — by author, measure and stated confidence — why findings were turned down, and what the tests showed.
GET/api/v1/approvals
read:growth
Sends waiting for, or given, a person’s approval.
GET/api/v1/actions
read:growth
Proposed changes, newest first: what each would do, whether the workspace’s limits allowed it, who proposed it, and what became of it.
POST/api/v1/actions
write:actions
Propose a change. It is planned and checked against the workspace’s limits exactly as an agent’s proposal is, then waits for a person in Proposed changes. Nothing here approves it or carries it out.
POST/api/v1/contacts
write:contacts
Add or update up to 100 contacts, the way an import does: an address on the do-not-contact list is skipped, tags are merged, and the plan’s contact allowance applies.
POST/api/v1/track
write:events
Report that one of your contacts did something in your own systems, such as trial_started. It starts the active workflows listening for that event, and says how many it started.
GET/api/v1/customers
read:contacts
The customer base in aggregate, and the people in one stage of it, with what each has spent per currency.
GET/api/v1/revenue
read:analytics
Revenue from the order ledger, per currency and never added across currencies, with how much of it is traced to marketing.
GET/api/v1/usage
read:analytics
What this workspace has used of each monthly allowance, and what remains.
GET/api/v1/connections
read:analytics
Each connected store, ad account, email platform and social account, and whether it is still delivering.
GET/api/v1/events
read:events
The events a webhook can subscribe to, oldest first from a cursor, for a caller that would rather poll.
GET/api/v1/agents
read:agents
Every agent in this workspace, Xyranik’s own and your own, with what each may do, the most it may ask for, and when it last acted. Read only: registering an agent or giving it a credential stays with a person.
GET/api/v1/agents/tools
read:agents
The tools an agent can be permitted here and every action each one has — its risk, the data it uses, whether it can be undone. These keys are what an authorize call names.
GET/api/v1/agents/rules
read:agents
The rules in force for agents in this workspace, each as a sentence built from its structure rather than stored prose.
GET/api/v1/agents/requests
read:agents
Every decision the gateway has made, newest first: what was asked, what was decided, which checks passed, which rules bit, and what became of it. Refusals included — how often the rules bite is the evidence that they work.

Opened by an agent’s own credential

These carry no scope, and that is not an omission. An agent credential grants nothing by itself — what the agent may do is decided for each request by the gateway, against the workspace’s permissions, the data the action would use, the risk, and the rules the owner wrote.

EndpointScopeWhat it answers

POST/api/v1/agent/authorize
agent credential
May this agent do this, here, now? Judged by the same gateway that judges Xyranik’s own agents. `requires_approval` is not a yes — `mayProceed` says plainly whether to go ahead.
POST/api/v1/agent/result
agent credential
What became of something this agent was allowed to do. Recorded against that decision, and only for one belonging to this workspace and this agent. Kept as unverified: a report of success is a claim, not a check.
GET/api/v1/agent/me
agent credential
What this agent is and what it may ask for: its permissions in words, the most it may ask for, its own limits, and whether the workspace has stopped its agents.

/api/v1/agents/… and /api/v1/agent/… differ by one letter and by which credential opens them. The plural reads the workspace’s agents with a workspace token; the singular is one agent asking about itself and asking permission.

The live list

Served by the API rather than written out, so it is true of the deployment you are calling:

IndexExample

curl "$XYRANIK_HOST/api/v1"
curl "$XYRANIK_HOST/api/v1/openapi.json"

Both are public: they hold no workspace data, and a developer deciding which scopes to ask for needs to read them before holding a token.