# Tools

Shared tool discovery, durable invocation and usage receipts.

See the [OpenAPI document](/openapi.json) for schemas and operation IDs.

## Prerequisites

- Protected operations require an API key in `x-api-key` or a browser session cookie; some actions require a verified user session
- Tenant-scoped operations use `X-Organization-Id`; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/tool-calls` | [List recent workspace tool invocations](#list-recent-workspace-tool-invocations) |
| `GET` | `/v1/api/tool-calls/{callId}` | [Read a persisted tool result and cost status](#read-a-persisted-tool-result-and-cost-status) |
| `GET` | `/v1/api/tools` | [Search available tools and inspect funding readiness](#search-available-tools-and-inspect-funding-readiness) |
| `GET` | `/v1/api/tools/{toolId}` | [Read the accepted input schema and execution policy](#read-the-accepted-input-schema-and-execution-policy) |
| `POST` | `/v1/api/tools/{toolId}/call` | [Create or revisit a durable tool invocation](#create-or-revisit-a-durable-tool-invocation) |
| `DELETE` | `/v1/api/tools/connections/treg` | [Remove a workspace Treg connection](#remove-a-workspace-treg-connection) |
| `GET` | `/v1/api/tools/connections/treg` | [Read safe Treg connection state](#read-safe-treg-connection-state) |
| `PUT` | `/v1/api/tools/connections/treg` | [Save a workspace Treg connection](#save-a-workspace-treg-connection) |

## List recent workspace tool invocations

`GET /v1/api/tool-calls` · operation ID `listToolCalls`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | query | no | string | Filter by project. |
| `limit` | query | no | string | 1–100, defaults to 30. |
| `cursor` | query | no | string | Opaque nextCursor from the previous page. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolCallList | Newest first, with stable keyset pagination. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read a persisted tool result and cost status

`GET /v1/api/tool-calls/{callId}` · operation ID `getToolCall`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `callId` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolCall | Execution and cost settle independently. Native accounting belongs to the named service; null actual costs are not zero. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such tool or call in this workspace. |

## Search available tools and inspect funding readiness

`GET /v1/api/tools` · operation ID `searchTools`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `query` | query | no | string | Search text, up to 500 characters. |
| `provider` | query | no | string | Provider filter. |
| `limit` | query | no | string | 1–100, defaults to 30. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolSearchResult | Native and upstream tool descriptors. Remote totals may be unknown. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read the accepted input schema and execution policy

`GET /v1/api/tools/{toolId}` · operation ID `describeTool`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `toolId` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolDescriptor | Tool descriptor. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such tool or call in this workspace. |

## Create or revisit a durable tool invocation

`POST /v1/api/tools/{toolId}/call` · operation ID `callTool`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `toolId` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `ToolCallInput` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `funding` | `auto` \| `hlix` \| `organization` | no |  |
| `idempotencyKey` | string | **yes** | min length 1, max length 200 |
| `input` | object | **yes** |  |
| `maxCostMicros` | integer (int64) | no | min 0, max 9007199254740991 — Provider reservation budget in USD micros. Actual settlement may exceed this amount. |
| `projectId` | string | no | min length 1 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolCall | Same idempotency key and request: the existing invocation. |
| `201` | ToolCall | New invocation persisted before provider dispatch. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `402` | ApiError | Insufficient workspace spending headroom for this reservation. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such tool or call in this workspace. |
| `409` | ApiError | This key already identifies a different request, or the selected connection is unavailable. |

## Remove a workspace Treg connection

`DELETE /v1/api/tools/connections/treg` · operation ID `removeToolConnection`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolConnection | The connection was removed. Owner or admin only. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read safe Treg connection state

`GET /v1/api/tools/connections/treg` · operation ID `getToolConnection`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolConnection | Credential presence, never the token. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Save a workspace Treg connection

`PUT /v1/api/tools/connections/treg` · operation ID `saveToolConnection`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `SaveToolConnection` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | **yes** | min length 1, max length 10000 |
| `organizationId` | string | **yes** | max length 40 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ToolConnection | The encrypted connection was saved. Owner or admin only. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## If a request fails

The response table for each operation lists its documented errors. Common status codes include:

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — check the resource ID and your access to the selected Workspace.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)