> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute API tool

> Sends an API tool's saved request once, filling its input placeholders from the inputs in the body. The call stops at the tool's timeout or 18 seconds, whichever is shorter, and nothing is saved.



## OpenAPI

````yaml /specs-prettified/realtime/openapi.stable.json post /v1/stable/api-tool/{toolID}/execute
openapi: 3.0.0
info:
  title: Realtime
  description: Realtime gateway API service
  version: 1.0.0
  contact: {}
servers:
  - url: https://realtime-api.voiceflow.com
security: []
tags: []
paths:
  /v1/stable/api-tool/{toolID}/execute:
    post:
      tags:
        - API Tool
      summary: Execute API tool
      description: Sends an API tool's saved request once, filling its input
        placeholders from the inputs in the body. The call stops at the tool's
        timeout or 18 seconds, whichever is shorter, and nothing is saved.
      operationId: StableAPIToolController_execute
      parameters:
        - name: toolID
          required: true
          in: path
          schema:
            type: string
          x-vf-doc:
            description: The ID of the API tool to execute.
          description: The ID of the API tool to execute.
        - name: projectID
          required: true
          in: query
          schema:
            type: string
            description: The ID of the project to operate on.
        - name: environmentAlias
          required: true
          in: query
          schema:
            type: string
            description: The alias of the environment to operate on (e.g. `main`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StableAPIToolExecuteRequest"
      responses:
        "200":
          description: Returns the endpoint's HTTP status, status text, headers, and
            parsed body, with success, latencyMs, and error fields. Secret
            values read [secret] wherever they appear.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StableAPIToolExecuteResponse"
          x-vf-doc:
            description: Returns the endpoint's HTTP status, status text, headers, and
              parsed body, with success, latencyMs, and error fields. Secret
              values read [secret] wherever they appear.
      security:
        - token: []
components:
  schemas:
    StableAPIToolExecuteRequest:
      type: object
      properties:
        inputs:
          default: {}
          description: A value for each of the API tool's input variables, keyed by input
            name. Each value replaces the tool's {input_name} placeholder in the
            URL, headers, query and body. Every declared input needs a value,
            and a name the tool does not declare is refused. List them with
            get_schema.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ExecuteInputString"
      additionalProperties: false
    ExecuteInputString:
      type: string
      description: "A value sent to a tool for one run, never stored. Plain text.
        {secret_name} inserts a project secret: the server fills in the value
        this environment would use in a conversation, and the value reads
        [secret] wherever it appears in the result. Brace text is a token when
        the text between the braces has no space at either end and holds only
        letters, digits, underscores, inner spaces, ., [, ], $ or -. A token
        that names no project secret, such as {customer_id} or {var name}, is
        refused before the tool runs, because a single run has no conversation
        to read a variable from: pass the value itself. Any other brace text is
        sent as written, so code, JSON and GraphQL such as query { user { id } }
        run as they are. Compact brace text such as {id} still reads as a token:
        write { id } to send it as text. A secret whose name is not letters,
        digits and underscores cannot be referenced. A {secret_name} token is
        filled in only in a top-level string value of inputs. Inside a nested
        object or array it is sent as written, and no secret is filled in."
    StableAPIToolExecuteResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the tool ran and reported no error.
        latencyMs:
          type: number
          description: How long the run took, in milliseconds, measured by this API around
            the call.
        error:
          nullable: true
          description: Why the run failed when `success` is false, otherwise null. Secret
            values read `[secret]`.
          type: string
        truncated:
          type: boolean
          description: Whether a returned payload was over 64 KB and was cut to its first
            64 KB of JSON text, which then arrives as a string.
        output:
          nullable: true
          description: What the endpoint returned. Null only when general-runtime did not
            answer in time.
          allOf:
            - $ref: "#/components/schemas/StableAPIToolExecuteOutput"
      required:
        - success
        - latencyMs
        - error
        - truncated
        - output
    StableAPIToolExecuteOutput:
      type: object
      properties:
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The HTTP status the endpoint returned. 408 when it did not answer
            within the tool's timeout or 18 seconds, whichever is shorter.
        statusText:
          type: string
          description: The HTTP status text the endpoint returned.
        headers:
          type: object
          additionalProperties:
            type: string
          description: The response headers. Secret values read `[secret]`.
        body:
          description: The response body, parsed as JSON when the endpoint returned JSON.
            Secret values read `[secret]`.
      required:
        - status
        - statusText
        - headers
        - body
  securitySchemes:
    token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Voiceflow bearer token
````