Tools
CompozyOS Tools HTTP endpoints.
GET
workspace_id*stringWorkspace id or reference
OK
application/json- response
grants*array<>total*integercurl -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", "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "tool_id": "string", "workspace_id": "string" } ], "total": 0}PUT
workspace_id*stringWorkspace id or reference
JSON request body
application/json- body
agent_name?stringdecision*stringValue in
"allow""reject"scope*stringValue in
"agent""tool"tool_id*stringStored
application/json- response
grant*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", "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "tool_id": "string", "workspace_id": "string" }}DELETE
id*stringRemembered approval grant id
workspace_id*stringWorkspace id or reference
Revoked
curl -X DELETE "https://example.com/api/tool-approval-grants/string?workspace_id=string"Empty
GET
workspace_id?stringEffective workspace id
workspace?stringEffective workspace reference
session_id?stringEffective session id
agent_name?stringEffective agent name
profile?stringAct as this profile by name
OK
application/json- response
tools*array<>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" } } ]}GET
id*stringStable approval id
profile?stringProfile that owns the approval
OK
application/json- response
approval_status*stringerror?unknownexecution_status?stringexpires_at?|Format
date-timeresult?unknowncurl -X GET "https://example.com/api/tools/approvals/string"{ "approval_status": "string", "error": null, "execution_status": "string", "expires_at": "2019-08-24T14:15:22Z", "result": null}POST
id*stringStable approval id
profile?stringProfile that owns the approval
Canceled
application/json- response
approval_status*stringerror?unknownexecution_status?stringexpires_at?|Format
date-timeresult?unknowncurl -X POST "https://example.com/api/tools/approvals/string/cancel"{ "approval_status": "string", "error": null, "execution_status": "string", "expires_at": "2019-08-24T14:15:22Z", "result": null}POST
id*stringStable approval id
profile?stringProfile that owns the approval
JSON request body
application/json- body
decision*stringValue in
"approved""denied"Decision recorded; execution may still be running
application/json- response
approval_status*stringerror?unknownexecution_status?stringexpires_at?|Format
date-timeresult?unknowncurl -X POST "https://example.com/api/tools/approvals/string/resolve" \ -H "Content-Type: application/json" \ -d '{ "decision": "approved" }'{ "approval_status": "string", "error": null, "execution_status": "string", "expires_at": "2019-08-24T14:15:22Z", "result": null}POST
profile?stringAct as this profile by name
JSON request body
application/json- body
agent_name?stringlimit?integerquery*stringsession_id?stringworkspace_id?stringOK
application/json- response
tools*array<>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
id*stringCanonical tool id
workspace_id?stringEffective workspace id
workspace?stringEffective workspace reference
session_id?stringEffective session id
agent_name?stringEffective agent name
profile?stringAct as this profile by name
OK
application/json- response
tool*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" } }}POST
id*stringCanonical tool id
profile?stringAct as this profile by name
JSON request body
application/json- body
agent_name?stringinput?unknowninput_digest?stringsession_id*stringworkspace_id?stringCreated
application/json- response
approval*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" }}POST
id*stringCanonical tool id
profile?stringAct as this profile by name
JSON request body
application/json- body
agent_name?stringapproval_token?stringcorrelation_id?stringinput*unknownsensitive_input_fields?array<string>session_id?stringtool_call_id?stringturn_id?stringworkspace_id?stringCompleted
application/json- response
duration_ms*integerFormat
int64events*array<>result*status*stringtool_id*stringtruncated*booleancurl -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": "approval_rejected", "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, "trust": "string" }, "status": "string", "tool_id": "string", "truncated": true}GET
workspace_id*stringWorkspace id
session_id*stringSession id
agent_name?stringEffective agent name
OK
application/json- response
tools*array<>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" } } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
agent_name?stringlimit?integerquery*stringsession_id?stringworkspace_id?stringOK
application/json- response
tools*array<>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" } } ]}GET
workspace_id*stringDurable workspace id
artifact_id*stringOpaque content-addressed artifact id
offset?integerZero-based byte offset
Format
int64limit?integerPage size in bytes; defaults to and is capped at 65536
Format
int64OK
application/json- response
artifact*bytes*integerFormat
int64data_base64*stringeof*booleannext_offset*integerFormat
int64offset*integerFormat
int64total_bytes*integerFormat
int64curl -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}