# Endpoints

Base URL: `https://gateway.apiosk.com` (Gateway v2). Every request carries
`Authorization: Bearer apk_access_…` — the token from `https://apiosk.com/skill/references/connecting.md`
— or a legacy `apk_live_…` agent key. Bodies are JSON and unknown fields are
refused, so send exactly the fields below.

Amounts are micro-USD integer strings: `"1000000"` is $1, `"230000"` is $0.23.

## `GET /v2/sources`

Published sources, grouped and paged. Free.

| Parameter | Effect |
| --- | --- |
| `search` | names, descriptions, metadata and capabilities |
| `category`, `tag`, `sector`, `capability` | an exact value from an earlier page |
| `offset`, `limit` | paging; `limit` is 1–50 |

Returns `sources` (each with `slug`, `name`, `description`, `category`,
`tags`, `sectors`, `capabilities`, `input_types`, `endpoint_count`, and
for a grouped source `service_count` and `services`), `total`, `offset`,
`next_offset` (null at the end), and the available `categories` and
`sectors`. The first unfiltered page (offset 0, no search or filter) also
lists the directory's `capabilities` and its 60 most common `tags`; other
pages leave those two out, and each source keeps its own on its row.

## `GET /v2/sources/{id}/endpoints`

One source's endpoints, paged with `search`, `service`, `offset` and
`limit` (1–100). Each item's `endpoint` carries `planner_available` and the
`inputs` it takes. Free.

## `POST /v2/discover`

Plans and prices a data question. Costs nothing.

```bash
curl -s "https://gateway.apiosk.com/v2/discover" \
  -H "Authorization: Bearer $APIOSK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"7b0f5c2e-6a51-4a4e-9d0a-3c1f2e8b9a10",
       "question":"Company profile and latest filed accounts for Mollie B.V. in the Netherlands"}'
```

| Field | |
| --- | --- |
| `request_id` | required. A new UUID per request; reuse it only to resend the identical request |
| `question` | required. The user's question in their words, up to 4,000 characters |
| `state` | the latest complete `state`, for a new question about the same task. Omit it for a separate task |
| `context_delta` | `explicit_values` and `requested_focus_refs`, using entity references the task returned |

Every task response has the same shape:

```json
{
  "protocol_version": "2",
  "request_id": "…",
  "status": "requires_approval",
  "context_view": { "approval_mode": "chatbot", "execution_mode": "server", "events_path": "/v2/tasks/…/events?…" },
  "proposal": {
    "quote_ref": "…",
    "currency": "USD",
    "max_total_atomic": "230000",
    "expires_at": "…",
    "approval_url": "https://app.apiosk.com/gateway-v2?task=…",
    "steps": ["…"]
  },
  "result": null,
  "billing": null,
  "next_actions": [{ "action_id": "…", "kind": "supply_input", "label": "…", "requires_authorization": false, "input_schema": {} }],
  "state": { "schema_version": "2", "state_ref": "…", "revision": 3, "expires_at": "…", "focus": {}, "state_token": "…" },
  "errors": []
}
```

`state.state_ref` is the task id. Keep it: it is what recovery reads.

**`max_total_atomic` is the most that can come off the balance** for the whole
plan. Quote the user that one total. `billing` carries what was actually
charged (`total_charged`) and a breakdown; the breakdown is secondary detail,
not a second price to quote.

## `POST /v2/workflows/{slug}/start`

A fixed workflow instead of a free-text question. Costs nothing until it
is approved like any other plan.

```json
{ "request_id": "…", "input": { "name": "Mollie B.V.", "country": "NL", "registration": "<the registry number the user gave>" } }
```

`european-company-dossier` covers NL, GB, FR, BE, FI, NO, LV, EE, SE, DK and SK;
`tender-company-dossier` covers NL and FR. Use only identifiers the user or a
source supplied.

`pre-kyb-screening` covers NL, GB and FR. Supply `name`, `country` and
`screening_level` (`Standard` or `Enhanced`). Optional inputs are
`registration`, `domain`, `iban`, and `vat_country` paired with
`vat_number` without its country prefix. Standard checks company identity
and potential sanctions matches plus supplied optional details; Enhanced adds
available country-specific records and mail DNS. Review the returned coverage
and exact price before approval. This preliminary Pass / Review / Reject result
complements full KYB/KYC; wallet screening is not included.

## `POST /v2/approve`

**This is the step that spends money.** Only when
`context_view.approval_mode` is `chatbot`, and only after the user chose
Approve. It approves this exact ceiling within the connection's spending limits
and starts the whole plan on the server.

```json
{ "request_id": "<new uuid>", "state": { "…": "the newest state, verbatim" }, "quote_ref": "<proposal.quote_ref>", "max_total_atomic": "<proposal.max_total_atomic>" }
```

Returns the task. A refusal is `403` with `approval_per_request_limit`,
`approval_daily_limit` or `approval_balance_insufficient`, and nothing was
charged. When `approval_mode` is `app`, do not call this: give the user
`proposal.approval_url`.

## `GET /v2/tasks/{id}`

The task, as it is now: status, results, `billing` and `next_actions`. Free,
and strictly a read — it never plans, approves or buys. This is also recovery:
after a timeout, a lost state or an interrupted response, read the task before
doing anything else.

## `GET /v2/tasks/{id}/events`

Server-sent updates for a running task. Open `https://gateway.apiosk.com` +
`context_view.events_path` exactly as returned; the path is signed, needs no
Authorization header and expires after 30 minutes. Polling `GET
/v2/tasks/{id}` every few seconds does the same job.

## `POST /v2/execute`

Continues the task with one returned `next_actions` entry: supply an input,
select an entity, run or retry a quoted step, read a result page, or cancel.

```json
{
  "request_id": "<new uuid>",
  "action_id": "<next_actions[].action_id>",
  "state": { "…": "the newest state, verbatim" },
  "quote_ref": "<proposal.quote_ref, for a paid step>",
  "idempotency_key": "<one UUID for this action, reused on every retry>",
  "input": { "value": "…" }
}
```

**One idempotency key per action, reused on every retry of that same action.**
A fresh key on a timeout is a second purchase. This is the single most expensive
mistake available in this API, which is why it is also in `SKILL.md` and in
`https://apiosk.com/skill/references/troubleshooting.md`.

The action's `input_schema` is authoritative: `supply_input` usually takes
`{"value": …}`, `select_entity` takes `{"entity_ref": …}`, and
`execute_quoted_step`, `poll` and `cancel` take `null`. A paid step needs
the current `proposal.quote_ref`. With `execution_mode: "server"` the server
runs an approved plan by itself — do not drive it step by step.

## Downloads

Report and evidence links in a task (`context_view.report.download_path`,
`report.evidence_download_path`, result `assets`) are paths on `https://gateway.apiosk.com`.
They are signed; open them as returned.

## `GET /v2/balance`

What the account holds. Free.

## The public REST API, as an alternative

The same token also works on Gateway v2's public API, which trades the task
protocol for simpler request and run objects: `POST /v2/ask` with
`{"question": "…", "execution_mode": "plan"}` returns a priced plan,
`POST /v2/asks/{id}/run` with `{"max_spend": …}` approves and runs it, and
`GET /v2/runs/{id}?wait_seconds=10` follows it. `GET /v2/sources/{id}` lists a
source's operations and `POST /v2/sources/{id}/run` calls one directly. Running
approves within this connection's spending limits, so the same rule applies:
the user approves the price first. Send `Idempotency-Key` on `POST /v2/ask`
and `POST /v2/sources/{id}/run`, reused on every retry; an ask runs once.

## The skill itself

`GET https://api.apiosk.com/functions/v1/agent-gateway/v1/skill` serves `SKILL.md` — this same document — to an agent
holding a token, and `GET https://api.apiosk.com/functions/v1/agent-gateway/v1/skill/references/<name>.md` the rest.
Useful if you have a connection but have lost the folder.
