VocalDocscontracts 1.65.0

Bind tools of a Connection to an Agent

POST /v1/tool-bindings

PropertyValue
Operationcreate_tool_binding
GroupTool bindings
Scopeintegrations:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited integrations.tool_binding.create (mutation)
Released in1.60.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates a binding at revision 1 (1.60.0): each tool with its model-facing name, constraints, projection, deadline and flag, its upstream contract digest pinned from the Connector's manifest or the registration's accepted pin. Every issue is a detail of validation_failed (ToolBindingIssueCode); a revoked Connection is connection_revoked; a send tool is refused with capability_not_available until the consent check of roadmap slice 2.15 exists.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the integrations:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/tool-bindings" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_...",
    "connection_id": "con_...",
    "tools": [
      {
        "tool": "<tool>"
      }
    ]
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ToolBindingCreateRequest.

FieldTypeRequiredDescription
agent_idAgentIdyes
connection_idConnectionIdyes
toolsarray of ToolBindingToolInputyes

Responses

StatusContent typeShapeError codes
201application/jsonToolBinding
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeconnection_revoked, idempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed, capability_not_available
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is ToolBinding.

FieldTypeRequiredDescription
agent_idAgentIdyes
binding_sha256Sha256HexyesThe digest of the canonical binding (toolBindingSha256Source), which a frozen copy and a grant name.
connection_idConnectionIdyes
connector_idConnectorId or nullyes
connector_versionstring or nullyesThe manifest version the tools were pinned from; null for an MCP server.
created_atTimestampyes
idToolBindingIdyes
mcp_server_idMcpServerId or nullyes
object"tool_binding"yes
organization_idOrganizationIdyes
originConnectionOriginyes
revisionintegeryes
toolsarray of ToolBindingToolyes
updated_atTimestampyes