Custom Tools

GET /api/orgs/{org_id}/custom-tools

List Custom Tools

List custom tools for the organization.

Omit limit to get every tool; total is the full count either way.

Parameters

Name	In	Type	Required	Description
include_usage	query	boolean	no	Populate calls_30d, agent_count, reference_count and deletion_safety. Left off they are null (= not computed, not zero). Opt-in because it adds a fixed five queries per call, two of which read the org’s live process definitions and agent instructions — worth it for the code-tools table, wasted on the resource pickers that also call this endpoint.
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized tools.

Responses

Status	Description	Body
200	Successful Response	Page_CustomToolResponse_
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/custom-tools

Create Custom Tool

Create a new custom tool. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
env_vars	string[]	no
name	string	yes
source_code	string	yes
tags	string[]	no

Responses

Status	Description	Body
201	Successful Response	CustomToolResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/custom-tools/{id_or_slug}

Get Custom Tool

Get a custom tool by ID or slug.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CustomToolResponse
422	Validation Error	HTTPValidationError

PUT /api/orgs/{org_id}/custom-tools/{id_or_slug}

Update Custom Tool

Update a custom tool. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
env_vars	string[]	no
is_enabled	boolean	no
name	string	no
source_code	string	no
tags	string[]	no

Responses

Status	Description	Body
200	Successful Response	CustomToolResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/custom-tools/{id_or_slug}

Delete Custom Tool

Delete a custom tool. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/custom-tools/{id_or_slug}/execute

Execute Custom Tool

Execute a custom tool (by ID or slug) with provided arg bindings.

Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
arg_bindings	object	no

Responses

Status	Description	Body
200	Successful Response	CustomToolRunResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/custom-tools/{id_or_slug}/revisions

List Custom Tool Revisions

List a code tool’s version history, newest first (by tool ID or slug).

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CustomToolRevisionSummary[]
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/custom-tools/{id_or_slug}/runs

List Tool Runs

List recent runs for a custom tool.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CustomToolRunResponse[]
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/custom-tools/{id_or_slug}/runs/{run_id}

Get Tool Run

Get a specific tool run by ID.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CustomToolRunResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/custom-tools/{id_or_slug}/usage

Get Custom Tool Usage

Who still uses this code tool — calls, process references, instruction references.

A dedicated sub-resource rather than fields on GET /{id_or_slug}, for the same reason /runs is one: the tool row is fetched on every render of the tool page and by the editor, while this needs a per-agent aggregate plus a scan of every live process definition and agent instruction in the org. Folding it in would put that cost on paths that never show it.

Requires org membership — reading usage is a member right, like history.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes
window_days	query	integer	no	Call window in days. References are not windowed.

Responses

Status	Description	Body
200	Successful Response	CustomToolUsageResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/custom-tools/validate

Validate Source

Validate Python source code without saving. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
env_vars	string[]	no
source_code	string	yes

Responses

Status	Description	Body
200	Successful Response	ValidateSourceResponse
422	Validation Error	HTTPValidationError