Agent quickstart
An AI agent can find Sisoco One, read its prices, get a key and make paid calls within a budget its owner set, with no browser. Everything below is plain HTTP.
1. Discover
GET https://api.sisoco.co.uk/llms.txt: what the service is, how to get a key, where everything is.GET https://api.sisoco.co.uk/mcp/server-card: the MCP server card (remote URL, auth header, protocol versions).GET https://api.sisoco.co.uk/openapi.json: every REST operation and error.GET https://api.sisoco.co.uk/v1/pricing: prices as JSON (no key): the price of one lookup (£0.02), what each operation costs, plans, credit packs and add-ons.
2. Get a key
- No key: the keyless trial answers
GET /v1/checkand the read-only MCP tools, 25 lookups per client IP per day. - Preview key:
POST /v1/preview/keysreturns a free read-only key once (30-day expiry). - Agent key: minted by the account owner on the account page, never by an API call. It carries a mandate: scopes, a monthly budget, a per-purchase ceiling and an expiry.
| Mandate | Default | |
|---|---|---|
| Scopes | read + watch |
purchase is opt-in |
| Monthly budget | £29 | the cheapest paid plan; spend is checked against the ledger before every metered call and every charge |
| Per-purchase ceiling | £29 | |
| Expiry | 90 days | renewed by the owner |
| Purchases | at most 3 an hour and 10 a day per key |
The owner is emailed at 80% and 100% of the budget, and can revoke every agent key in one action. An agent key cannot mint keys or change its own mandate.
3. Price a call before making it
Add estimate=true to any metered GET. Nothing runs upstream and nothing is charged; the answer is the cost the call would have:
GET /v1/check?company=<number|LEI|name>&country=GB&estimate=true
{ "data": { "estimate": true, "operation": "GET /v1/check", "units": 1, "quota_lookups_remaining": 99, "budget_remaining_minor": 2898 },
"meta": { "request_id": "req_…", "cost": { "unit": "lookup", "quantity": 1, "unit_price_minor": 2, "currency": "GBP", "cost_minor": 2 } } }
4. Read the cost of every call
Every successful metered answer carries meta.cost: quantity lookups at unit_price_minor, in currency minor units, cost_minor in all. It is the amount written to the spend ledger for that request and counted against an agent key's budget. A failed call is refunded and has no cost; a replayed answer (Idempotent-Replayed: true) is not charged again. With an API key, each successful answer, and each definitive "not found", costs the units stated for the operation (1 lookup for every lookup), including answers served from cache; other errors are refunded. Without a key: 25 lookups per client IP per UTC day; answers served from cache cost nothing. Once an IP's allowance is used, each distinct client on it gets 5 more a day (at most 20 per IP). Sample companies 03959649, 00519500, 2138001S47XKWIB7TH90, 552032534 are always free.
5. Stay within the budget
| Error | Meaning | next_action |
|---|---|---|
402 budget_exceeded |
the call or purchase would pass the monthly budget or the per-purchase ceiling | ask_owner |
403 mandate_scope |
the mandate lacks the scope (or the route is owner-only) | ask_owner |
429 quota_exceeded |
the plan's lookups are used up and no credit is left | upgrade |
429 rate_limited |
too many requests, or too many purchases | retry or ask_owner |
6. Buy credits (purchase scope)
POST /v1/credits/purchase
Idempotency-Key: <a new unique string per purchase>
{ "pack": "credits-1000" }
Charged off-session to the owner's saved card. The Idempotency-Key is required: retry with the same key and you get the same answer, never a second charge; a different body with the same key is 409 idempotency_conflict. If the bank asks for authentication you get 402 authentication_required and the owner is emailed; nothing was charged.
What the scopes allow
purchase: credit packs, plans, add-ons — and renewals
The purchase scope lets the agent buy credit packs (POST /v1/credits/purchase) and start or change the plan and add-ons (POST /v1/subscription), off-session, within the budget and the per-purchase ceiling. Credit packs are one-off. A plan or add-on is a subscription: only the first, prorated charge is the agent's purchase and counts against its budget. After that the subscription renews at the end of every billing period (monthly or yearly) on the owner's card, whoever started it, and keeps renewing after the agent key expires or is revoked. Renewals are not agent purchases and are not limited by any agent mandate. To stop them, the owner cancels in the billing portal, or a purchase-scoped key sets the plan to free (cancels at the end of the period). Grant purchase only to agents you trust to commit you to a recurring charge.
watch: watchlists and webhook endpoints
The watch scope covers every write an agent may make: watchlists and webhook endpoints. An agent with watch can register a webhook endpoint at any public HTTPS URL it chooses, and the account's events on watched entities (company names, officers, notices) are then delivered there. Endpoints stay after the agent key is revoked. Review the account's endpoints on the account page or with GET /v1/webhooks, and delete any you do not recognise (DELETE /v1/webhooks/{id}); every registration is in the account audit log with the key that made it. If an agent should only read, mint it without watch.
Next
- MCP setup, including how to treat tool output.
- Errors and rate limits.