---
title: "Execute tool"
method: POST
path: "/v1/tools/{id}/execute"
tags: ["Tool"]
---

# Execute tool

`POST /v1/tools/{id}/execute`

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

## Path parameters

- `id` string, required

## Request body

- ExecuteToolRequest
  - `env` EnvVar[] — Set of key-value pairs to add to the tool's execution environment.
    - `name` string, required
    - `secret_id` string
    - `value` string
  - `http` HTTPTool — Configuration for HTTP requests and authentication.
    - `allow` HTTPToolAllow[] — List of allowed HTTP hosts and associated authentication.
      - `auth` HTTPToolAuth — Authentication configuration for outbound requests to this host.
        - `basic` HTTPToolBasic
          - `password` string
          - `secret_id` string
          - `user_id` string
        - `bearer` HTTPToolBearer — Configuration to add an 'Authorization' header using the 'Bearer' scheme.
          - `secret_id` string
          - `token` string — The token to set, e.g. 'Authorization: Bearer <token>'.
        - `query` HTTPToolQuery
          - `key` string
          - `secret_id` string
          - `value` string
      - `host` string — The hostname to allow.
  - `input` unknown
  - `revision_id` string — 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.

## Response `200`

OK

- ExecuteToolResponse
  - `execution` Execution, required — The execution details of the Tool.
    - `exit_code` integer, required
    - `stderr` string, required
    - `stdout` string, required
  - `output` unknown, required
  - `output_status` 'error' | 'json_serialization_error' | 'valid', required — 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.

## Other responses

- `401` — Unauthenticated error response

## Changes

- **2025-02-05** `4ca61d8b4e33` — 6 breaking, 2 info
  - the request property `http` became not nullable
  - the request property `http/allow/items/auth/basic` became not nullable
  - the request property `http/allow/items/auth/bearer` became not nullable
  - the request property `http/allow/items/auth/query` became not nullable
  - …4 more
- **2024-12-05** `9a6cae8060b4` — 1 breaking
  - the `output` response's property type/format changed from `string`/`` to ``/`` for status `200`
- **2024-11-06** `6a6ef20cc3e9` — 2 info
  - api operation id `executeTool` was added
  - api tag `Tool` added
- **2024-10-31** `333818f2f208` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/riza-io/apis/execute/changes/v1/tools/:id/execute/post.md)

---

[API](https://skmtc.dev/riza-io/apis/execute.md) · [All operations](https://skmtc.dev/riza-io/apis/execute/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riza-io/execute/revisions/4ca61d8b4e33/schema)