> ## Documentation Index > Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Approve a pending tool call > Approves a tool call the agent paused on, in response to a toolApprovalRequested event. The tool then runs. ## OpenAPI ````yaml /widgets-api-spec.yml post /v1/conversations/{id}/tool_calls/{toolCallId}:approve openapi: 3.1.0 info: title: Cadenya Widgets API description: >- Browser-facing API for the embeddable Cadenya chat widget. The customer's backend authenticates the visitor and creates the initial session. The browser renews that same session through RenewWidgetSession using its existing bearer token and required workspace ID, with no session ID in the request. Both return tokenExpiresAt and sessionExpiresAt; renewal never extends the session deadline. Renewal requires a valid token with 60 seconds of clock-skew tolerance; hard session expiry has no tolerance. Management credentials remain server-side. Terminal session errors never create a replacement. The only unauthenticated route is the widget config. version: '1.0' servers: - url: https://{widgetHost} description: The Widget host returned in a Widget Session's info.host variables: widgetHost: default: adbtaawrmh4h.widgets.cadenya.com security: - bearerAuth: [] tags: - name: WidgetConfigService description: |- Serves the widget's presentation config. The only unauthenticated surface: the widget is identified by the hostname and the edge enforces the origin allowlist; no session or token is required. - name: WidgetConversationEventStreamsService description: |- Server-streaming events over SSE. A separate service so deployments can route it around the JSON transcoder to a dedicated stream server — the transcoder cannot produce text/event-stream. - name: WidgetConversationService description: |- Conversations between the session's visitor and the widget's agent. All routes are token-implicit: scope comes entirely from the bearer's claims, and a conversation outside that scope 404s indistinguishably from one that does not exist. - name: WidgetSessionService description: |- Renews the caller's existing session token. Session identity comes only from the verified bearer token; no caller-supplied ID selects a session. paths: /v1/conversations/{id}/tool_calls/{toolCallId}:approve: post: tags: - WidgetConversationService - Conversations summary: Approve a pending tool call description: >- Approves a tool call the agent paused on, in response to a toolApprovalRequested event. The tool then runs. operationId: WidgetConversationService_ApproveToolCall parameters: - name: id in: path description: Conversation ID. required: true schema: type: string - name: toolCallId in: path description: >- The tool call awaiting a decision, from the toolApprovalRequested event. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ApproveToolCallRequest' required: true responses: '200': description: OK content: {} '401': description: >- Unauthenticated. TOKEN_EXPIRED identifies verified access-token expiry at or beyond exp + 60 seconds before execution. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. Never retry renewal recursively. Missing, malformed, or invalid tokens do not authorize renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '403': description: >- Permission denied. SESSION_REVOKED or SESSION_EXPIRED is terminal. Management authorization failures never trigger visitor-token renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '429': description: >- Resource exhausted. SESSION_EXHAUSTED is terminal; rate limiting uses a distinct reason and may include Retry-After. content: application/json: schema: $ref: '#/components/schemas/Status' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: typescript label: TypeScript source: >- import CadenyaWidgets from '@cadenya/widgets'; const client = new CadenyaWidgets(); await client.conversations.approveToolCall('_123', { toolCallId: "sample" }); - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\tcadenyawidgets \"go.cadenya.com/cadenya-widgets-go\"\n)\n\nfunc main() {\n\tclient, err := cadenyawidgets.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenyawidgets.ConversationApproveToolCallParams{\n\t\tToolCallID: \"sample\",\n\t}\n\tif err := client.Conversations().ApproveToolCall(ctx, \"_123\", params); err != nil {\n\t\tlog.Fatal(err)\n\t}\n}" - lang: python label: Python source: |- from cadenya_widgets import CadenyaWidgets with CadenyaWidgets() as client: client.conversations.approve_tool_call("_123", tool_call_id="sample") - lang: ruby label: Ruby source: >- require "cadenya-widgets" client = CadenyaWidgets::Client.new client.conversations.approve_tool_call("_123", tool_call_id: "sample") - lang: bash label: CLI source: |- cadenya-widgets conversations approve-tool-call _123 \ --tool-call-id sample - lang: shell label: curl source: |- curl --request POST \ --url '/v1/conversations/_123/tool_calls/tool_call_123:approve' \ --header "Authorization: Bearer ${CADENYAWIDGETS_API_KEY}" components: schemas: ApproveToolCallRequest: type: object properties: id: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: Conversation ID. toolCallId: readOnly: true type: string description: >- The tool call awaiting a decision, from the toolApprovalRequested event. description: Approve tool call request. Responds to a toolApprovalRequested event. Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: anyOf: - $ref: '#/components/schemas/WidgetSessionErrorInfo' - $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). WidgetSessionErrorInfo: type: object description: >- google.rpc.ErrorInfo detail for widget lifecycle failures. Match both domain and reason; ignore unknown reasons rather than renewing automatically. required: - '@type' - domain - reason properties: '@type': type: string enum: - type.googleapis.com/google.rpc.ErrorInfo domain: type: string enum: - api.cadenya.com reason: $ref: '#/components/schemas/WidgetSessionErrorReason' metadata: type: object additionalProperties: type: string description: Optional non-sensitive context. Never contains tokens or secrets. GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. WidgetSessionErrorReason: type: string description: >- TOKEN_EXPIRED identifies access-token expiry beyond the 60-second clock-skew tolerance. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. SESSION_* reasons are terminal. Never infer renewability from HTTP status alone. enum: - TOKEN_EXPIRED - SESSION_REVOKED - SESSION_EXPIRED - SESSION_EXHAUSTED securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.