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

# Execute tool

> Execute a tool with a given input. The input is validated against the tool's input schema.



## OpenAPI

````yaml post /v1/tools/{id}/execute
openapi: 3.0.3
info:
  title: Execute
  version: 0.1.4
servers:
  - url: https://api.riza.io
security:
  - bearerHttpAuthentication: []
paths:
  /v1/tools/{id}/execute:
    post:
      tags:
        - Tool
      summary: Execute tool
      description: >-
        Execute a tool with a given input. The input is validated against the
        tool's input schema.
      operationId: executeTool
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteToolRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteToolResponse'
          description: OK
        '401':
          content:
            application/json:
              examples:
                unauthenticated:
                  value:
                    code: 16
                    message: unauthenticated
              schema:
                $ref: '#/components/schemas/Status'
          description: Unauthenticated error response
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Riza from '@riza-io/api';

            const client = new Riza({
              apiKey: process.env['RIZA_API_KEY'], // This is the default and can be omitted
            });

            const response = await client.tools.exec('id');

            console.log(response.execution);
        - lang: Python
          source: |-
            import os
            from rizaio import Riza

            client = Riza(
                api_key=os.environ.get("RIZA_API_KEY"),  # This is the default and can be omitted
            )
            response = client.tools.exec(
                id="id",
            )
            print(response.execution)
        - lang: Go
          source: |
            package main

            import (
              "context"
              "fmt"

              "github.com/riza-io/riza-api-go"
              "github.com/riza-io/riza-api-go/option"
            )

            func main() {
              client := riza.NewClient(
                option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RIZA_API_KEY")
              )
              response, err := client.Tools.Exec(
                context.TODO(),
                "id",
                riza.ToolExecParams{

                },
              )
              if err != nil {
                panic(err.Error())
              }
              fmt.Printf("%+v\n", response.Execution)
            }
components:
  schemas:
    ExecuteToolRequest:
      properties:
        env:
          description: Set of key-value pairs to add to the tool's execution environment.
          items:
            $ref: '#/components/schemas/EnvVar'
          type: array
        http:
          $ref: '#/components/schemas/HTTPTool'
        input:
          description: >-
            The input to the tool. This must be a valid JSON-serializable
            object. It will be validated against the tool's input schema.
        revision_id:
          description: >-
            The Tool revision ID to execute. This optional parmeter is used to
            pin executions to specific versions of the Tool. If not provided,
            the latest (current) version of the Tool will be executed.
          type: string
      type: object
    ExecuteToolResponse:
      properties:
        execution:
          $ref: '#/components/schemas/ExecutionResult'
        output:
          description: The returned value of the Tool's execute function.
        output_status:
          description: >-
            The status of the output. "valid" means your Tool executed
            successfully and returned a valid JSON-serializable object, or void.
            "json_serialization_error" means your Tool executed successfully,
            but returned a nonserializable object. "error" means your Tool
            failed to execute.
          enum:
            - error
            - json_serialization_error
            - valid
          type: string
      required:
        - output
        - output_status
        - execution
      type: object
    Status:
      properties:
        code:
          description: >-
            The status code, which should be an enum value of
            [google.rpc.Code][google.rpc.Code].
          type: integer
        message:
          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.
          type: string
      type: object
    EnvVar:
      description: Set of key-value pairs to add to the tool's execution environment.
      properties:
        name:
          type: string
        secret_id:
          type: string
        value:
          type: string
      required:
        - name
      type: object
    HTTPTool:
      description: Configuration for HTTP requests and authentication.
      properties:
        allow:
          description: List of allowed HTTP hosts and associated authentication.
          items:
            $ref: '#/components/schemas/HTTPToolAllow'
          type: array
      type: object
    ExecutionResult:
      description: The execution details of the function.
      properties:
        duration:
          description: The execution time of the function in milliseconds.
          type: integer
        exit_code:
          description: >-
            The exit code returned by the function. Will often be '0' on success
            and non-zero on failure.
          type: integer
        id:
          description: The ID of the execution.
          type: string
        stderr:
          description: The contents of 'stderr' after executing the function.
          type: string
        stdout:
          description: The contents of 'stdout' after executing the function.
          type: string
      required:
        - id
        - exit_code
        - stdout
        - stderr
        - duration
      type: object
    HTTPToolAllow:
      description: List of allowed HTTP hosts and associated authentication.
      properties:
        auth:
          $ref: '#/components/schemas/HTTPToolAuth'
        host:
          description: The hostname to allow.
          type: string
      type: object
    HTTPToolAuth:
      description: Authentication configuration for outbound requests to this host.
      properties:
        basic:
          $ref: '#/components/schemas/HTTPToolBasic'
        bearer:
          $ref: '#/components/schemas/HTTPToolBearer'
        query:
          $ref: '#/components/schemas/HTTPToolQuery'
      type: object
    HTTPToolBasic:
      properties:
        password:
          type: string
        secret_id:
          type: string
        user_id:
          type: string
      type: object
    HTTPToolBearer:
      description: >-
        Configuration to add an 'Authorization' header using the 'Bearer'
        scheme.
      properties:
        secret_id:
          type: string
        token:
          description: 'The token to set, e.g. ''Authorization: Bearer <token>''.'
          type: string
      type: object
    HTTPToolQuery:
      properties:
        key:
          type: string
        secret_id:
          type: string
        value:
          type: string
      type: object
  securitySchemes:
    bearerHttpAuthentication:
      scheme: bearer
      type: http

````