Tools

Shared tool discovery, durable invocation and usage receipts.

See the OpenAPI document 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
GET	/v1/api/tool-calls/{callId}	Read a persisted tool result and cost status
GET	/v1/api/tools	Search available tools and inspect funding readiness
GET	/v1/api/tools/{toolId}	Read the accepted input schema and execution policy
POST	/v1/api/tools/{toolId}/call	Create or revisit a durable tool invocation
DELETE	/v1/api/tools/connections/treg	Remove a workspace Treg connection
GET	/v1/api/tools/connections/treg	Read safe Treg connection state
PUT	/v1/api/tools/connections/treg	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

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.