Call a source

This is the shortest paid call Apiosk has. No model interprets anything: you name the source and the operation, and Apiosk runs exactly that. Requires sources:execute.

Request

POST /v1/execute/{source}/{operation}
POST /v2/execute/{source}/{operation}

Both paths are the same endpoint. The body is the operation’s inputs and nothing else:

curl https://gateway.apiosk.com/v1/execute/kvk-dutch-business-register/company_registry.search \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Idempotency-Key: nomi-request-983472" \
  -H "Content-Type: application/json" \
  -d '{"company.name":"Mollie B.V."}'

Query parameter	Type	Default	Meaning
`max_spend`	decimal USD	none	Refuse before paying if the plan’s maximum cost is higher
`wait_seconds`	integer 0–55	25	How long to wait for the result before answering `202`
`limit`	integer 1–50	none	Cap the number of result documents returned

The Idempotency-Key header is optional and strongly recommended; see Idempotency.

What the path accepts

The source must have a currently executable operation in its source detail. A discovery-only directory entry cannot be called.

Source: its id, its name, or a provider that groups several sources (pulsenetwork), case-insensitive. For a group, the call runs on the member that offers the operation; if two members offer it, you get 409 ambiguous_operation naming them, and call one by its own id.
Operation: its capability (company_registry.search), its endpoint id, or its name.
Variants: some operations have several variants with different inputs — a KVK lookup by KVK number or by branch number. The call runs the variant whose inputs you supply; if none fits, 422 lists what each variant needs.

What the body accepts

Each input may be named three ways, so you can use whichever you have:

Form	Example
The fact type, as `GET /v2/sources/{id}` lists it	`{"company.name": "Mollie B.V."}`
The name the source’s own API uses	`{"naam": "Mollie B.V."}`
The last word, when it is unambiguous for that operation	`{"name": "Mollie B.V."}`

Response

The amounts below illustrate the response shape, not a current KVK quote. Read the source detail for the current buyer price before running. 200 with the finished run:

{
  "id": "6f0b…",
  "status": "completed",
  "question": "Run company_registry.search on kvk-dutch-business-register",
  "plan": {
    "quote_ref": "b41c…",
    "expires_at": "2026-09-22T18:12:04Z",
    "steps": [
      {
        "source_id": "kvk-dutch-business-register",
        "operation": "company_registry.search",
        "name": "Company search",
        "conditional": false,
        "estimated_cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" }
      }
    ],
    "estimated_total": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" }
  },
  "answer": null,
  "data": {},
  "results": [
    {
      "result_ref": "a72e…",
      "source": { "provider": "kvk-dutch-business-register", "name": "KVK Business Register" },
      "data": {}
    }
  ],
  "usage": {
    "sources": [
      { "source_id": "kvk-dutch-business-register", "operation": "company_registry.search", "calls": 1,
        "cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" } }
    ],
    "cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" },
    "held": { "amount": 0, "amount_micro_usd": "0", "currency": "USD" }
  },
  "balance": { "remaining": { "amount": 47.797, "amount_micro_usd": "47797000", "currency": "USD" } },
  "errors": []
}

object

The source’s own document, present when the run produced exactly one — which a direct call normally does. The same document is in results[0].data.

object

Where the result came from: source, operation, retrieval time, the source’s page, the record’s own links, subject, identifiers such as a KVK number, and cost. Present on every entry of results, and at the top level when there is one. See Sales signals.

object

What the ledger actually charged. It equals the sum of usage.sources[].cost.

object

Money reserved for a call that has not settled yet. It is released or charged when the call resolves.

object

The organisation’s balance after this run.

Status codes

Status	Code	Meaning
200	—	The run finished; read `status` for `completed`, `partial`, `unsupported` or `needs_input`
202	—	Still running after `wait_seconds`; poll `GET /v2/runs/{id}`
400	`invalid_request`	Malformed body, `max_spend`, `limit` or `Idempotency-Key`
401	`invalid_api_key`	See Authentication
402	`insufficient_balance`	Top up the organisation’s balance
402	`spend_limit_exceeded`	`limit` says which ceiling: `per_request`, `monthly` or `max_spend`
403	`insufficient_scope`	The key lacks `sources:execute`
404	`source_not_found`	No purchasable source has this id or name
404	`operation_not_found`	The source has no such operation; `operations` lists what it has
409	`idempotency_conflict`	The same key with a different body
409	`ambiguous_operation`	Two sources in a group offer this operation; `sources` names them
422	`invalid_source_input`	A field is unknown, missing, or does not match its schema
429	`rate_limit_exceeded`	Wait, then retry with the same `Idempotency-Key`
502	`source_error`	The source could not complete the run

Everything that refuses before a purchase says so: nothing was charged.

{
  "error": {
    "code": "invalid_source_input",
    "message": "Required inputs are missing. Nothing was charged.",
    "missing": ["company.name"]
  }
}

A direct call buys only the named source. If an operation needs an input that only another source can supply, Apiosk refuses with 422 rather than buying that other source for you. Supply the input, or use Ask.

The explicit form

POST /v2/sources/{source_id}/run

{
  "operation": "company_registry.search",
  "input": { "company.name": "Mollie B.V." },
  "max_spend": 1.00,
  "wait_seconds": 25
}

Same engine, price and response. Use it when a client builds requests from the catalogue and prefers a named envelope over a path.

Buy data

Use cases

Operating it

API Reference

Ask

Request

What the path accepts

What the body accepts

Response

Status codes

The explicit form

​Request

​What the path accepts

​What the body accepts

​Response

​Status codes

​The explicit form

Request

What the path accepts

What the body accepts

Response

Status codes

The explicit form