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

# Attach or update a tool on an agent

> Idempotent insert-or-update of one (agent_id, tool_name) row. Both POST and PUT are accepted.



## OpenAPI

````yaml /api-spec/openapi.yaml post /api/v1/agents/{id}/tools
openapi: 3.1.0
info:
  contact:
    name: Kataven
    url: https://kataven.ai
  description: |
    The Kataven Hub API is the management surface for the Kataven voice AI
    platform. Use it to create and configure voice agents, manage tools and
    knowledge, wire up telephony, run outbound campaigns, embed the chat
    widget, and read account-level settings.

    ## Authentication

    Two credential shapes are accepted on every protected endpoint:

    - **`sk_live_<account>_<rest>`** — long-lived API key. The token
      self-identifies the account, so `X-Account-ID` is not required.
      Recommended for SDK / MCP / CI / any server-to-server use. Mint via
      Hub UI → **Settings → API Keys**.
    - **Zitadel JWT** (`eyJ…`, ~1h TTL) — interactive admin sessions from
      the Hub UI. Requires the `X-Account-ID` header for tenant resolution.

    Public endpoints (`/api/accounts/*`, `/api/login`, the widget auth
    endpoints under `/api/v1/widget/auth/*`) require no Authorization
    header.

    ## Multi-tenancy

    Every protected request operates on the per-account PostgreSQL database
    identified by `X-Account-ID` (or by the `sk_live_` prefix). There is no
    cross-tenant surface; an account is a hard isolation boundary. The
    reserved account `kataven-admin` is rejected with `403`.

    ## Base URLs

    Routes are mounted at both `/` and `/hub-api/` for compatibility. SDKs
    default to the `/hub-api/` prefix on `hub.kataven.ai`, or `/v1/` on
    `api.kataven.ai`.
  license:
    name: Proprietary
  title: Kataven Hub API
  version: 0.2.0
servers:
  - url: https://api.kataven.ai/v1
    description: Production (recommended for SDKs)
  - url: https://hub.kataven.ai/hub-api/api
    description: Production (legacy path, kept for back-compat)
  - url: http://localhost:8081
    description: Local development (api-server only)
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: >-
      CRUD for voice agents — the configurable units that hold a system prompt,
      voice, model, and tool/playbook/FAQ associations.
  - name: Tools
    description: Built-in and custom tools an agent can call during a conversation.
  - name: Playbooks
    description: >-
      Reusable knowledge bundles (system prompt fragments + a list of tool
      names) that can be attached to one or more agents.
  - name: FAQs
    description: Question/answer entries surfaced to agents as quick-lookup knowledge.
  - name: Marketplace
    description: Browse and install agent templates.
  - name: Integrations
    description: >-
      Third-party integrations (Stripe, Shopify, etc.) — credentials stored
      encrypted via the Secret Encryptor service.
  - name: Telephony
    description: Carrier credentials and phone-number assignment.
  - name: Calls
    description: Outbound call origination.
  - name: Recordings
    description: Call recording retrieval (presigned URL).
  - name: Call Limits
    description: >-
      Per-tenant cost caps (read-only via SDK — set by the platform team based
      on plan tier).
  - name: Campaigns
    description: Bulk-dial outbound campaigns from CSV.
  - name: API Keys
    description: >-
      sk_live_ server-to-server credentials. CRUD is gated to Hub UI auth (a
      leaked sk_live_ cannot mint another).
  - name: Widget Keys
    description: pk_live_ public identifiers used by the embeddable widget bootstrap.
  - name: Widget Admin
    description: Branding + per-agent widget policy.
  - name: Widget Auth
    description: >-
      Public cross-origin auth endpoints called from customer-page widgets (used
      by `@kataven/client`, not the server SDK).
externalDocs:
  description: ''
  url: ''
paths:
  /api/v1/agents/{id}/tools:
    post:
      tags:
        - Agents
      summary: Attach or update a tool on an agent
      description: >-
        Idempotent insert-or-update of one (agent_id, tool_name) row. Both POST
        and PUT are accepted.
      operationId: postApiV1AgentsByIdTools
      parameters:
        - description: Tenant database. Required when using a Zitadel JWT.
          in: header
          name: X-Account-ID
          schema:
            type: string
        - description: Agent id
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/data.AgentTool'
              description: Tool config
              summary: body
        description: Tool config
        required: true
      responses:
        '200':
          description: Saved
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Invalid body
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Database error
      security:
        - bearerAuth: []
components:
  schemas:
    data.AgentTool:
      properties:
        agent_id:
          example: agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
          type: string
        config:
          type: object
        enabled:
          example: true
          type: boolean
        tool_name:
          example: lookup_order
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      in: header
      name: Authorization
      type: apiKey

````