---
title: "List tools"
method: GET
path: "/v1/tools"
tags: ["Agents"]
---

# List tools

`GET /v1/tools`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/tools`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Org-owned custom tools plus PyAI prebuilt tools. Requires the `omni:session` scope.

## Response `200`

Tools

- ToolList
  - `object` string
  - `data` Tool[]
    - `object` string
    - `id` string
    - `org_id` string, nullable
    - `name` string
    - `kind` 'prebuilt' | 'custom'
    - `description` string
    - `input_schema` object
    - `config_schema` ToolConfigSchema: Declares the settings a tool needs. Render these as a form in your agent builder; capture answers on the agent's tool binding config.
      - `fields` ToolConfigField[]
        - `key` string, required
        - `label` string, required
        - `type` 'string' | 'number' | 'boolean' | 'select', required
        - `required` boolean
        - `secret` boolean: When true, the value is encrypted at rest and never returned in plaintext.
        - `help` string
        - `placeholder` string
        - `options` string[]: Allowed values when type is 'select'.
    - `webhook_url` string, nullable
    - `execution` 'hosted' | 'server' | 'engine' | 'client': How the tool runs. hosted = PyAI runs it (prebuilt read catalog). server = the tool-executor calls your webhook. engine = the Omni call engine runs it natively (call control: transfer_to_human, send_dtmf, play_hold, collect, end_call), not routed to the executor. client = your connected app.
    - `auth_header` string, nullable
    - `has_auth` boolean: Whether a webhook auth secret is configured (the secret itself is never returned).
    - `side_effect` 'read' | 'action'
    - `timeout_ms` integer
    - `status` 'active' | 'disabled'
    - `created_at` integer
  - `has_more` boolean

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)