Built for agents to drive, beside your staff
Retavon's API was shaped for AI agents first, and the web app your staff use was built on top of it. An agent can do any job a person can do on screen, under the same permissions, and you can see every step it took.
A key for each agent, with the limits you choose
A key that acts for a person holds what they hold, and its work is theirs in the audit trail. A key that acts for nobody holds the roles you give it. Either can be read-only, which refuses every write whatever its roles. Keys last 90 days unless you choose otherwise, up to a year, and can be rotated or revoked at any time.
{
"name": "Claude Desktop, front counter",
"acts_for": "me",
"read_only": true,
"expires_in_days": 30,
"password": "your own password, entered again"
}
Keys are issued, rotated and revoked on this screen as well as through the API. From the staging sandbox, with made-up staff; its seeded keys were made without an end date, while a key issued here or through the API works for 1 to 365 days.
Every record says what can happen next
A record with a status carries next: the operations its state allows, each with its method, path and why. An agent reads its options from the record in front of it instead of from a manual. A fresh quote offers these, among others:
"next": [
{ "operation_id": "openSalesOrder",
"why": "The customer has agreed: make the quote an order." },
{ "operation_id": "getQuoteDocument",
"why": "Print the quote for the customer to take home." },
{ "operation_id": "emailQuote",
"why": "Email the quote to the customer." },
{ "operation_id": "addSalesOrderPackage",
"why": "Add a package (a spa with its cover, steps and delivery) to the quote." },
{ "operation_id": "cancelSalesOrder",
"why": "The customer will not go ahead." }
]Refusals say what is wrong and what to do
Errors are problem documents with a stable code, a detail written for the reader, whether a retry could help, and a typed next pointing at the operation to try instead. When the database refuses something, the reply states what happened with the numbers, then what to do. This is the reply to a request with no key:
{
"status": 401,
"code": "unauthenticated",
"title": "Authentication required",
"detail": "Send a valid API key in the Authorization header: 'Authorization: Bearer rtv_...'. If this key used to work, it has expired, been revoked, or the staff member it acts for has left: a person signs in again; an agent asks the person it works for for a new key.",
"retryable": false,
"next": [
{ "operation_id": "signIn", "method": "POST", "path": "/v1/sign-in",
"why": "Sign in with your business, email and password for a new session." }
],
"request_id": "0bec6207-2e10-43a6-8de4-b73d1b11d37f"
}The numbers on the paperwork work as ids
People quote order numbers, SKUs and work order numbers, so where a record has one, the API takes it in place of the id: an order number, a SKU, a store's code, a customer number, a purchase order, a work order, a receipt or a gift card number. Every reply puts the name beside the id, so an agent can tell a person what it did in words they recognise.
{
"work_order_number": 1099,
"customer_name": "Sky Lowe",
"location_name": "Boise Showroom",
"equipment_name": "Sundance Optima (2012)",
...
}Money and stock move once
Every write that takes money or moves stock requires an idempotency_key, held unique in the database. An agent whose connection drops sends the same request again and the deposit is taken once. Here a quote becomes an order with its deposit, in one step:
{
"deposit": {
"payment_method_id": "01a11f0b-1210-7fda-81e7-e569b8344af6",
"amount": "2000.00",
"reference": "Check 4417"
},
"idempotency_key": "open-1042-deposit"
}An event feed that never skips
An agent that watches the business registers as an event consumer, reads what is new, and acknowledges what it has handled. The next read starts after the last event it acknowledged, so nothing is missed; events not yet acknowledged come back, so an agent handles each one in a way that is safe to repeat. The feed is pulled by the agent; Retavon does not call out to your URLs.
The API describes itself
More than 450 operations in one OpenAPI 3.1 document, named by the job a person at the store would do, not by table. Field descriptions are written for a reader who has never worked in the business. Any agent that can read an OpenAPI document and send an HTTPS request with a bearer key can work in Retavon.
Served from Retavon's staging API.
Questions
Can an agent do more than the person it works for?
No. A key that acts for a person holds exactly their permissions, and nobody, person or key, can grant a permission they do not hold.
How do I see what an agent did?
The audit trail records every change with the key that made it, the person it acts for, the time, and what the record was before. Filter it by person or by key.
Is there an MCP server?
No. The API is plain HTTPS with an OpenAPI 3.1 document, which agent tools can load directly.
Does Retavon send webhooks?
No. Agents read the event feed and acknowledge what they handle.
Which agents work with it?
Any that can send an HTTPS request with a bearer key and act on the replies. The key's name is yours to choose, so the audit trail says which agent did what.