Base URL https://api.stijnai.shop/v1. Everything the dashboard does is a public endpoint, authenticated with a bearer token from your profile page.
Your first run in three commands.
Create, fetch and list runs.
Teach an agent about your business.
What each code means and what to do.
Create a token on your profile page. Pass it as a bearer token on every request. Tokens can be revoked at any time without interrupting runs already in flight.
| Method | Path | Description |
|---|---|---|
| POST | /v1/runs | Create a run and execute it |
| GET | /v1/runs/{id} | Fetch a single run with output and trace |
| GET | /v1/runs | List runs, filterable by agent, status and date |
| GET | /v1/agents | List available agents and their rates |
| GET | /v1/balance | Current credit balance in cents |
| PUT | /v1/agents/{slug}/config | Replace an agent's configuration |
Returns 201 with the completed run. Runs are synchronous: the response arrives when the work is done, which for most agents is under two seconds. Research Analyst can take up to a minute, so set your client timeout accordingly.
Send an Idempotency-Key header and a retry with the same key returns the original run instead of creating and charging for a second one. Keys are remembered for 24 hours. Use the identifier of the thing you are processing, not a random value, so that a retry after a network failure is genuinely deduplicated.
Configuration is how an agent learns about your business. It is plain prose plus a little structure, stored per agent per account, and applied to every run automatically.
Setting abstain_below makes the agent decline rather than guess when its confidence falls under the threshold. The run still costs the normal rate, but you get an explicit abstention instead of a confident mistake.
Register an endpoint and every completed run is posted to it. Deliveries are retried with exponential backoff for 24 hours, and each carries an HMAC signature in the X-Signature header computed over the raw body with your webhook secret.
| Code | Meaning | What to do |
|---|---|---|
| 400 | Input failed validation | Check it against the agent's input shape |
| 401 | Token missing or revoked | Issue a new token on the profile page |
| 402 | Insufficient credit | Top up; nothing was run or charged |
| 404 | No such agent or run | Check the slug against /v1/agents |
| 409 | Idempotency key reused with different input | Use a new key |
| 422 | Agent ran but could not produce valid output | Not charged; inspect the run trace |
| 429 | Rate limited | Honour the Retry-After header |
| 503 | Agent temporarily unavailable | Not charged; retry with backoff |
120 runs per minute per account, and 600 read requests per minute. Exceeding either returns 429 with a Retry-After header. If you need more, open a ticket — the limit exists to protect the platform, not to sell you an upgrade.
The version is in the path. We will not change the meaning of a field inside v1. New optional fields may be added, so parse defensively and ignore what you do not recognise. Breaking changes ship as v2 with at least six months of overlap.