---
title: Tool Calls
description: 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](/docs/api/reference) for what that means.

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

Every operation below requires a Bearer token. See [Authentication](/docs/concepts/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**

```json
{
  "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**

```bash
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](/docs/api/reference/schemas#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**

```json
{
  "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**

```bash
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**

```json
{
  "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**

```bash
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**

```bash
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**

```json
{
  "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**

```bash
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**

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