# 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](/developers/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.