Skip to content
Core ConceptsCLI ReferenceAPI Reference
CompozyOS RuntimeAPI Reference

Tools

Compozy Tools HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

List remembered native-tool approval decisions for one workspace

GET/api/tool-approval-grants

Query Parameters

workspace_id*string

Workspace id or reference

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/tool-approval-grants?workspace_id=string"
{  "grants": [    {      "agent_name": "string",      "created_at": "2019-08-24T14:15:22Z",      "decision": "allow",      "id": "string",      "input_digest": "string",      "last_used_at": "2019-08-24T14:15:22Z",      "tool_id": "string",      "workspace_id": "string"    }  ],  "total": 0}

Set an explicit agent-wide or tool-wide native-tool approval decision

PUT/api/tool-approval-grants

Query Parameters

workspace_id*string

Workspace id or reference

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/tool-approval-grants?workspace_id=string" \  -H "Content-Type: application/json" \  -d '{    "decision": "allow",    "scope": "agent",    "tool_id": "string"  }'
{  "grant": {    "agent_name": "string",    "created_at": "2019-08-24T14:15:22Z",    "decision": "allow",    "id": "string",    "input_digest": "string",    "last_used_at": "2019-08-24T14:15:22Z",    "tool_id": "string",    "workspace_id": "string"  }}

Revoke one remembered native-tool approval decision in one workspace

DELETE/api/tool-approval-grants/{id}

Path Parameters

id*string

Remembered approval grant id

Query Parameters

workspace_id*string

Workspace id or reference

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/tool-approval-grants/string?workspace_id=string"
Empty

List operator-visible registry tools

GET/api/tools

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

session_id?string

Effective session id

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/tools"
{  "tools": [    {      "availability": {        "authorized": true,        "available": true,        "conflicted": true,        "enabled": true,        "executable": true,        "reason_codes": [          "approval_canceled"        ],        "registered": true      },      "decision": {        "agent_policy_result": "string",        "approval_required": true,        "availability_result": "string",        "callable": true,        "hook_result": "string",        "reason_codes": [          "approval_canceled"        ],        "registry_policy_result": "string",        "session_policy_result": "string",        "source_policy_result": "string",        "system_permission_mode": "string",        "visible_to_operator": true,        "visible_to_session": true      },      "descriptor": {        "backend": {          "extension_id": "string",          "handler": "string",          "kind": "native_go",          "mcp_server": "string",          "mcp_tool": "string",          "native_name": "string",          "requires_capabilities": [            "string"          ]        },        "concurrency_safe": true,        "description": "string",        "destructive": true,        "display_title": "string",        "friendly_verb": "string",        "input_schema": null,        "input_schema_digest": "string",        "max_result_bytes": 0,        "open_world": true,        "output_schema": null,        "output_schema_digest": "string",        "preview": "string",        "read_only": true,        "requires_interaction": true,        "risk": "read",        "search_hints": [          "string"        ],        "source": {          "kind": "builtin",          "owner": "string",          "raw_server_name": "string",          "raw_tool_name": "string",          "resource_id": "string",          "resource_version": "string",          "scope": "string",          "workspace_id": "string"        },        "tags": [          "string"        ],        "tool_id": "string",        "toolsets": [          "string"        ],        "visibility": "internal"      }    }  ]}

Search operator-visible registry tools

POST/api/tools/search

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/tools/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{  "tools": [    {      "availability": {        "authorized": true,        "available": true,        "conflicted": true,        "enabled": true,        "executable": true,        "reason_codes": [          "approval_canceled"        ],        "registered": true      },      "decision": {        "agent_policy_result": "string",        "approval_required": true,        "availability_result": "string",        "callable": true,        "hook_result": "string",        "reason_codes": [          "approval_canceled"        ],        "registry_policy_result": "string",        "session_policy_result": "string",        "source_policy_result": "string",        "system_permission_mode": "string",        "visible_to_operator": true,        "visible_to_session": true      },      "descriptor": {        "backend": {          "extension_id": "string",          "handler": "string",          "kind": "native_go",          "mcp_server": "string",          "mcp_tool": "string",          "native_name": "string",          "requires_capabilities": [            "string"          ]        },        "concurrency_safe": true,        "description": "string",        "destructive": true,        "display_title": "string",        "friendly_verb": "string",        "input_schema": null,        "input_schema_digest": "string",        "max_result_bytes": 0,        "open_world": true,        "output_schema": null,        "output_schema_digest": "string",        "preview": "string",        "read_only": true,        "requires_interaction": true,        "risk": "read",        "search_hints": [          "string"        ],        "source": {          "kind": "builtin",          "owner": "string",          "raw_server_name": "string",          "raw_tool_name": "string",          "resource_id": "string",          "resource_version": "string",          "scope": "string",          "workspace_id": "string"        },        "tags": [          "string"        ],        "tool_id": "string",        "toolsets": [          "string"        ],        "visibility": "internal"      }    }  ]}

Get one operator-visible registry tool

GET/api/tools/{id}

Path Parameters

id*string

Canonical tool id

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

session_id?string

Effective session id

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/tools/string"
{  "tool": {    "availability": {      "authorized": true,      "available": true,      "conflicted": true,      "enabled": true,      "executable": true,      "reason_codes": [        "approval_canceled"      ],      "registered": true    },    "decision": {      "agent_policy_result": "string",      "approval_required": true,      "availability_result": "string",      "callable": true,      "hook_result": "string",      "reason_codes": [        "approval_canceled"      ],      "registry_policy_result": "string",      "session_policy_result": "string",      "source_policy_result": "string",      "system_permission_mode": "string",      "visible_to_operator": true,      "visible_to_session": true    },    "descriptor": {      "backend": {        "extension_id": "string",        "handler": "string",        "kind": "native_go",        "mcp_server": "string",        "mcp_tool": "string",        "native_name": "string",        "requires_capabilities": [          "string"        ]      },      "concurrency_safe": true,      "description": "string",      "destructive": true,      "display_title": "string",      "friendly_verb": "string",      "input_schema": null,      "input_schema_digest": "string",      "max_result_bytes": 0,      "open_world": true,      "output_schema": null,      "output_schema_digest": "string",      "preview": "string",      "read_only": true,      "requires_interaction": true,      "risk": "read",      "search_hints": [        "string"      ],      "source": {        "kind": "builtin",        "owner": "string",        "raw_server_name": "string",        "raw_tool_name": "string",        "resource_id": "string",        "resource_version": "string",        "scope": "string",        "workspace_id": "string"      },      "tags": [        "string"      ],      "tool_id": "string",      "toolsets": [        "string"      ],      "visibility": "internal"    }  }}

Mint a local single-use approval token for one tool invocation

POST/api/tools/{id}/approvals

Path Parameters

id*string

Canonical tool id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/tools/string/approvals" \  -H "Content-Type: application/json" \  -d '{    "session_id": "string"  }'
{  "approval": {    "approval_token": "string",    "expires_at": "2019-08-24T14:15:22Z",    "input_digest": "string",    "tool_id": "string"  }}

Invoke a registry tool through executable dispatch

POST/api/tools/{id}/invoke

Path Parameters

id*string

Canonical tool id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/tools/string/invoke" \  -H "Content-Type: application/json" \  -d '{    "input": null  }'
{  "duration_ms": 0,  "events": [    {      "agent_name": "string",      "approval_mode": "string",      "correlation_id": "string",      "decision": "string",      "destructive": true,      "display_title": "string",      "duration_ms": 0,      "error_code": "tool_not_found",      "input_digest": "string",      "kind": "tool.call_started",      "open_world": true,      "read_only": true,      "reason_codes": [        "approval_canceled"      ],      "redacted_input_fields": [        "string"      ],      "result_bytes": 0,      "result_digest": "string",      "result_redaction_paths": [        "string"      ],      "risk": "read",      "session_id": "string",      "source_kind": "builtin",      "source_owner": "string",      "tool_id": "string",      "truncated": true,      "workspace_id": "string"    }  ],  "result": {    "artifacts": [      {        "bytes": 0,        "mime_type": "string",        "name": "string",        "sha256": "string",        "uri": "string"      }    ],    "bytes": 0,    "content": [      {        "data": null,        "metadata": {          "property1": null,          "property2": null        },        "mime_type": "string",        "text": "string",        "type": "string"      }    ],    "duration_ms": 0,    "metadata": {      "property1": null,      "property2": null    },    "preview": "string",    "redactions": [      {        "bytes": 0,        "path": "string",        "reason": "approval_canceled"      }    ],    "structured": null,    "truncated": true  },  "status": "string",  "tool_id": "string",  "truncated": true}

List session-callable registry tools

GET/api/workspaces/{workspace_id}/sessions/{session_id}/tools

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/tools"
{  "tools": [    {      "availability": {        "authorized": true,        "available": true,        "conflicted": true,        "enabled": true,        "executable": true,        "reason_codes": [          "approval_canceled"        ],        "registered": true      },      "decision": {        "agent_policy_result": "string",        "approval_required": true,        "availability_result": "string",        "callable": true,        "hook_result": "string",        "reason_codes": [          "approval_canceled"        ],        "registry_policy_result": "string",        "session_policy_result": "string",        "source_policy_result": "string",        "system_permission_mode": "string",        "visible_to_operator": true,        "visible_to_session": true      },      "descriptor": {        "backend": {          "extension_id": "string",          "handler": "string",          "kind": "native_go",          "mcp_server": "string",          "mcp_tool": "string",          "native_name": "string",          "requires_capabilities": [            "string"          ]        },        "concurrency_safe": true,        "description": "string",        "destructive": true,        "display_title": "string",        "friendly_verb": "string",        "input_schema": null,        "input_schema_digest": "string",        "max_result_bytes": 0,        "open_world": true,        "output_schema": null,        "output_schema_digest": "string",        "preview": "string",        "read_only": true,        "requires_interaction": true,        "risk": "read",        "search_hints": [          "string"        ],        "source": {          "kind": "builtin",          "owner": "string",          "raw_server_name": "string",          "raw_tool_name": "string",          "resource_id": "string",          "resource_version": "string",          "scope": "string",          "workspace_id": "string"        },        "tags": [          "string"        ],        "tool_id": "string",        "toolsets": [          "string"        ],        "visibility": "internal"      }    }  ]}

Search session-callable registry tools

POST/api/workspaces/{workspace_id}/sessions/{session_id}/tools/search

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/tools/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{  "tools": [    {      "availability": {        "authorized": true,        "available": true,        "conflicted": true,        "enabled": true,        "executable": true,        "reason_codes": [          "approval_canceled"        ],        "registered": true      },      "decision": {        "agent_policy_result": "string",        "approval_required": true,        "availability_result": "string",        "callable": true,        "hook_result": "string",        "reason_codes": [          "approval_canceled"        ],        "registry_policy_result": "string",        "session_policy_result": "string",        "source_policy_result": "string",        "system_permission_mode": "string",        "visible_to_operator": true,        "visible_to_session": true      },      "descriptor": {        "backend": {          "extension_id": "string",          "handler": "string",          "kind": "native_go",          "mcp_server": "string",          "mcp_tool": "string",          "native_name": "string",          "requires_capabilities": [            "string"          ]        },        "concurrency_safe": true,        "description": "string",        "destructive": true,        "display_title": "string",        "friendly_verb": "string",        "input_schema": null,        "input_schema_digest": "string",        "max_result_bytes": 0,        "open_world": true,        "output_schema": null,        "output_schema_digest": "string",        "preview": "string",        "read_only": true,        "requires_interaction": true,        "risk": "read",        "search_hints": [          "string"        ],        "source": {          "kind": "builtin",          "owner": "string",          "raw_server_name": "string",          "raw_tool_name": "string",          "resource_id": "string",          "resource_version": "string",          "scope": "string",          "workspace_id": "string"        },        "tags": [          "string"        ],        "tool_id": "string",        "toolsets": [          "string"        ],        "visibility": "internal"      }    }  ]}

Read one retained oversized tool-result page

GET/api/workspaces/{workspace_id}/tool-artifacts/{artifact_id}

Path Parameters

workspace_id*string

Durable workspace id

artifact_id*string

Opaque content-addressed artifact id

Query Parameters

offset?integer

Zero-based byte offset

Formatint64
limit?integer

Page size in bytes; defaults to and is capped at 65536

Formatint64

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/tool-artifacts/string"
{  "artifact": {    "bytes": 0,    "mime_type": "string",    "name": "string",    "sha256": "string",    "uri": "string"  },  "bytes": 0,  "data_base64": "string",  "eof": true,  "next_offset": 0,  "offset": 0,  "total_bytes": 0}

Marketplace

Compozy Marketplace HTTP endpoints.

Toolsets

Compozy Toolsets HTTP endpoints.