Generated HTTP reference for the 6 operations the published OpenAPI document describes under tool-calls.

Tool Calls

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET `/v1/tool-calls`

List tool calls across the project's sessions

Query parameters

Name	Type	Required	Description
`before`	`string`	no	—
`count_only`	`"true"` \| `"false"`	no	—
`limit`	`integer`	no	—
`since`	`string (date-time)`	no	—

Responses

Status	Body	Description
`200`	object \| object	OK
`400`	object	Bad Request — the body or query did not match the schema.

Example response

{
  "tool_calls": [
    {
      "id": "tc_0000000000000000",
      "session_id": "ses_0000000000000000",
      "server_id": "srv_0000000000000000",
      "tool_name": "Example",
      "status": "running",
      "called_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/tool-calls/{id}`

Read one tool call

Responses

Status	Body	Description
`200`	ToolCall	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`called_at`	`string (date-time)`	yes	—
`duration_ms`	`integer,null`	yes	—
`error_code`	`string,null`	yes	—
`failover_trail`	—	no	—
`id`	`string`	yes	`tc_`-prefixed: the bigserial with a `tc_` prefix prepended
`input`	—	no	—
`output`	—	no	—
`routing`	—	no	—
`server_id`	`string`	yes	—
`session_id`	`string`	yes	—
`status`	`"running"` \| `"success"` \| `"error"`	yes	—
`tool_name`	`string`	yes	—

Example response

{
  "id": "tc_0000000000000000",
  "session_id": "ses_0000000000000000",
  "server_id": "srv_0000000000000000",
  "tool_name": "Example",
  "status": "running",
  "called_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/tool-calls/{id}/payment-status`

Where a tool call's payment got to

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The tool call, as `tc_\<digits\>` or as the bare digits. Both are accepted and the response always echoes the prefixed spelling. Anything else — a UUID, a negative number, an empty segment — is refused 400 before any lookup, so a malformed id and an id belonging to another tenant are answered differently.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request. The id is neither `tc_\<digits\>` nor bare digits. BARE body — there is no `error.code` to read and no `request_id`.
`404`	object	Not Found. No tool call with this id is visible to this credential. BARE body.

Response 200

Field	Type	Required	Description
`events`	array of object	yes	—
`idempotency_key`	`string,null`	yes	The key the router stamped on the call and the provider echoed back. Null exactly when `payment_status` is `unknown`.
`original_status`	`string`	yes	The tool call's OWN status — whether the call itself ran — which is a different question from whether the money settled. A call can be `succeeded` here and `failed` in `payment_status`.
`payment_status`	`"pending"` \| `"succeeded"` \| `"failed"` \| `"refunded"` \| `"updated"` \| `"unknown"`	yes	—
`tool_call_id`	`string`	yes	Always `tc_`-prefixed, whichever spelling you sent.

Example response

{
  "tool_call_id": "tc_0000000000000000",
  "payment_status": "pending",
  "original_status": "string",
  "events": [
    {
      "event_type": "string",
      "received_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls/{id}/payment-status \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/tool-calls/{id}/payment-status/stream`

The same payment status, pushed as it changes (SSE)

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The tool call, as `tc_\<digits\>` or as the bare digits. Both are accepted and the response always echoes the prefixed spelling. Anything else — a UUID, a negative number, an empty segment — is refused 400 before any lookup, so a malformed id and an id belonging to another tenant are answered differently.

Responses

Status	Body	Description
`200`	—	The stream opened. `snapshot` first, then `update` per change, then `done`; heartbeat comments in between. The connection is closed by the server 5 seconds after a terminal status, or at 30 minutes, whichever comes first.
`400`	object	Bad Request. The id is neither `tc_\<digits\>` nor bare digits. BARE body — there is no `error.code` to read and no `request_id`.
`404`	object	Not Found. No tool call with this id is visible to this credential. BARE body.

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls/{id}/payment-status/stream \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/tool-calls/{id}/verification-status`

Where a tool call's identity check got to

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The tool call, as `tc_\<digits\>` or as the bare digits. Both are accepted and the response always echoes the prefixed spelling. Anything else — a UUID, a negative number, an empty segment — is refused 400 before any lookup, so a malformed id and an id belonging to another tenant are answered differently.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request. The id is neither `tc_\<digits\>` nor bare digits. BARE body — there is no `error.code` to read and no `request_id`.
`404`	object	Not Found. No tool call with this id is visible to this credential. BARE body.

Response 200

Field	Type	Required	Description
`events`	array of object	yes	—
`hosted_url`	`string,null`	yes	The buyer-facing verification link, read off the originating call's own output so you can re-show it while polling. Null on rails that score server-side and have no buyer-facing flow, and null when the output carried no such field — the two are not distinguishable here. Unlike `idempotency_key`, this field is present even on an `unknown` status.
`idempotency_key`	`string,null`	yes	Null exactly when `verification_status` is `unknown`.
`original_status`	`string`	yes	Whether the tool CALL ran, which is a different question from whether the buyer was verified.
`tool_call_id`	`string`	yes	Always `tc_`-prefixed, whichever spelling you sent.
`verification_status`	`"pending"` \| `"approved"` \| `"rejected"` \| `"expired"` \| `"review"` \| `"unknown"`	yes	—

Example response

{
  "tool_call_id": "tc_0000000000000000",
  "verification_status": "pending",
  "original_status": "string",
  "events": [
    {
      "event_type": "string",
      "received_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls/{id}/verification-status \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/tool-calls/{id}/verification-status/stream`

The same verification status, pushed as it changes (SSE)

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The tool call, as `tc_\<digits\>` or as the bare digits. Both are accepted and the response always echoes the prefixed spelling. Anything else — a UUID, a negative number, an empty segment — is refused 400 before any lookup, so a malformed id and an id belonging to another tenant are answered differently.

Responses

Status	Body	Description
`200`	—	The stream opened. `snapshot`, then `update` per change, then `done`, with heartbeat comments in between. Closed 5 seconds after `approved`, `rejected` or `expired`, or at 30 minutes.
`400`	object	Bad Request. The id is neither `tc_\<digits\>` nor bare digits. BARE body — there is no `error.code` to read and no `request_id`.
`404`	object	Not Found. No tool call with this id is visible to this credential. BARE body.

Example request

curl -X GET https://api.codespar.dev/v1/tool-calls/{id}/verification-status/stream \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

Tool Calls

Tool Calls

GET /v1/tool-calls

GET /v1/tool-calls/{id}

GET /v1/tool-calls/{id}/payment-status

GET /v1/tool-calls/{id}/payment-status/stream

GET /v1/tool-calls/{id}/verification-status

GET /v1/tool-calls/{id}/verification-status/stream

On this page

GET `/v1/tool-calls`

GET `/v1/tool-calls/{id}`

GET `/v1/tool-calls/{id}/payment-status`

GET `/v1/tool-calls/{id}/payment-status/stream`

GET `/v1/tool-calls/{id}/verification-status`

GET `/v1/tool-calls/{id}/verification-status/stream`