API reference
The four endpoints an agent uses.
This describes our published contract. Your API address comes with onboarding, and there is no public endpoint to call yet. All paths are relative to /v1. Authenticate as a workload identity with a bearer token.
POST /runtime/tool-requests
Submit a proposal. Scope: runtime:tool-request. Header: Idempotency-Key, equal to request_id.
| Field | Type | Notes |
|---|---|---|
request_id |
string | Your unique ID for this request |
agent.agent_id |
UUID | Must match the token's subject |
agent.session_id |
UUID | Your session |
tool.name |
string | A registered governed tool |
tool.arguments |
object | Exactly that tool's fields; unknown fields are refused |
context.instruction |
string | Up to 500 characters; untrusted free text |
context.timestamp |
date-time | When the agent decided to act |
Answers: 201 with request_id, decision, reason, execution, correlation_id and replayed. See Errors.
GET /runtime/tool-requests/{requestId}/result
Current status for a request this agent owns. Scope: runtime:tool-result. Never cached.
Answers: 200 with request_id, correlation_id, decision, reason, execution, outcome, receipt and observed_at. It leaves out target payloads.
GET /runtime/action-offers
Approved requests from people, offered to this agent. Scope: runtime:tool-request. Takes cursor and limit.
POST /runtime/action-offers/{actionId}/acceptances
Accept one offer. Executes nothing. Answers: 201, new or replayed, with requestId to poll.
Registered tools
| Tool | Arguments |
|---|---|
update_supplier_bank_account |
supplier_id, account_number, country_code, routing_code, beneficiary_name, reason |
update_supplier_contact |
supplier_id, contact_channel, contact_value, reason |
propose_action |
action_type, resource_type, resource_id, parameters, reason |
propose_action carries an action your organisation defined itself: action_type is the name
it registered, and parameters must match that action's registered fields. A field marked secret
is swapped for a token before anything is stored. These actions are held for a person's approval
by default, and connecting one to a real system is still in test.