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

# update a tool

> change a tool. `config` replaces the stored config whole, except that an `auth` block without a `token` / `password` keeps the stored credential (an empty string clears it).



## OpenAPI

````yaml /openapi.json patch /v1/tools/{tool_id}
openapi: 3.1.0
info:
  title: silk api
  version: 1.0.0
  description: >-
    rumik ai's speech api. synthesize speech with the expressive `muga` model,
    the faster `mulberry` model or the multilingual `mulberry-1.6` model over
    http or a streaming websocket session, run conversational voice agents over
    webrtc, a realtime pcm socket or the phone, and manage everything the agents
    playground does — agents, voices, variables, tools, phone numbers, sip
    trunks and outbound calls — with the same api key.
  contact:
    name: rumik ai
    url: https://rumik.ai
servers:
  - url: https://silk-api.rumik.ai
    description: production
security:
  - bearerAuth: []
tags:
  - name: speech
    description: text-to-speech over HTTP and WebSocket.
  - name: voice agents
    description: start calls with a deployed agent from your own app.
  - name: agents
    description: build, configure, deploy and inspect your agents.
  - name: calls
    description: place outbound phone calls and read call history.
  - name: voices
    description: the voices, languages and styles an agent may use.
  - name: variables
    description: account-wide `{name}` prompt variables and their defaults.
  - name: tools
    description: HTTP tools agents call before or during a call.
  - name: phone numbers
    description: 'numbers rented through rumik: search, rent, connect, release.'
  - name: sip trunks
    description: bring your own numbers over SIP.
paths:
  /v1/tools/{tool_id}:
    patch:
      tags:
        - tools
      summary: update a tool
      description: >-
        change a tool. `config` replaces the stored config whole, except that an
        `auth` block without a `token` / `password` keeps the stored credential
        (an empty string clears it).
      operationId: updateTool
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: the tool's id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolUpdateRequest'
            examples:
              default:
                value:
                  description: looks the caller's account up
                  config:
                    action: get
                    method: GET
                    url: https://api.example.com/v1/accounts
                    params:
                      - name: phone
                        value: '{phone_number}'
                    headers:
                      - name: Accept
                        value: application/json
                    auth:
                      type: bearer
                      token: sk-…
                    timeoutMs: 3000
                    outputs:
                      - name: firstName
                        path: ''
                      - name: plan
                        path: account.plan
      responses:
        '200':
          description: ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
              examples:
                default:
                  value:
                    id: 019f8e32-4d60-7f71-ac8d-9e0f1a2b3c4d
                    name: lookup_account
                    description: looks the caller's account up by phone number
                    kind: before_call
                    config:
                      action: get
                      performedAction: end_call
                      curl: ''
                      method: GET
                      url: https://api.example.com/v1/accounts
                      headers:
                        - name: Accept
                          value: application/json
                      params:
                        - name: phone
                          value: '{phone_number}'
                      body: ''
                      timeoutMs: 3000
                      waitForResponse: true
                      auth:
                        type: bearer
                        headerName: X-API-Key
                        username: ''
                        hasSecret: true
                      llmParams: []
                      outputs:
                        - name: firstName
                          path: ''
                        - name: plan
                          path: account.plan
                    isDefault: false
                    createdAt: '2026-09-11T10:00:00Z'
                    updatedAt: '2026-09-11T10:00:00Z'
        '401':
          description: >-
            `unauthorized` — key missing, malformed, unknown, revoked or
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    error: Invalid API key
                    code: unauthorized
        '403':
          description: '`forbidden_scope` — the key was created without the `agent` scope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden_scope:
                  value:
                    error: This API key lacks the 'agent' scope
                    code: forbidden_scope
        '404':
          description: '`agent_tool_not_found` — no such tool on this account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_tool_not_found:
                  value:
                    error: Tool not found
                    code: agent_tool_not_found
        '409':
          description: >-
            `agent_tool_name_taken` — another tool already has this name
            (case-insensitive). `agent_tool_name_reserved` — the name belongs to
            a built-in tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_tool_name_taken:
                  value:
                    error: A tool with this name already exists
                    code: agent_tool_name_taken
                agent_tool_name_reserved:
                  value:
                    error: This name belongs to a built-in tool
                    code: agent_tool_name_reserved
        '422':
          description: >-
            `agent_tool_invalid` — the config is not runnable — for example an
            HTTP tool with no `http(s)://` URL. `invalid_request` — a field is
            missing or malformed. `details` lists every failing field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_tool_invalid:
                  value:
                    error: The tool configuration is invalid
                    code: agent_tool_invalid
                invalid_request:
                  value:
                    error: >-
                      body.toNumber: must be an E.164 phone number, e.g.
                      +14155551234
                    code: invalid_request
                    details:
                      - loc: body.toNumber
                        message: must be an E.164 phone number, e.g. +14155551234
        '429':
          description: >-
            `rate_limited` — the key's per-minute budget is spent. `Retry-After`
            says how long to wait; the body carries `limit` and `current`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: Rate limit exceeded
                    code: rate_limited
                    limit: 100
                    current: 101
          headers:
            Retry-After:
              description: seconds to wait before retrying (per-key rate limit only).
              schema:
                type: integer
components:
  schemas:
    ToolUpdateRequest:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
        kind:
          anyOf:
            - $ref: '#/components/schemas/AgentToolKind'
            - type: 'null'
        config:
          anyOf:
            - $ref: '#/components/schemas/ToolConfigInput'
            - type: 'null'
      additionalProperties: false
      type: object
      title: ToolUpdateRequest
      description: |-
        Every field optional; ``config`` replaces the stored config whole (the
        dashboard always sends the full object), except that an omitted secret
        keeps the stored one.
    Tool:
      properties:
        id:
          type: string
          description: the tool's id (`default-…` for built-ins).
        name:
          type: string
        description:
          type: string
        kind:
          $ref: '#/components/schemas/AgentToolKind'
        config:
          $ref: '#/components/schemas/ToolConfig'
        isDefault:
          type: boolean
          default: false
          description: >-
            true for the platform's built-in tools, which cannot be edited or
            deleted.
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      type: object
      required:
        - id
        - name
        - description
        - kind
        - config
      title: Tool
      description: a tool as stored. the credential is never returned.
    Error:
      type: object
      properties:
        error:
          type: string
          description: human-readable error message.
        code:
          type: string
          description: machine-readable error code.
    AgentToolKind:
      type: string
      enum:
        - before_call
        - during_call
      title: AgentToolKind
      description: When in a call's life the agent reaches for the tool.
    ToolConfigInput:
      properties:
        action:
          $ref: '#/components/schemas/AgentToolAction'
          default: get
          description: >-
            `get` / `post` make an HTTP request; `perform` runs a built-in
            `performedAction` instead.
        performedAction:
          $ref: '#/components/schemas/AgentToolPerformedAction'
          default: end_call
          description: 'for `action: perform` — `end_call` or `transfer_call`.'
        curl:
          type: string
          maxLength: 16000
          default: ''
          description: free-form note (the dashboard's curl paste); not executed.
        method:
          $ref: '#/components/schemas/AgentToolHttpMethod'
          default: GET
          description: '`GET` or `POST` (others are coerced to `GET`).'
        url:
          type: string
          maxLength: 2048
          default: ''
          description: '`http(s)://…`. may contain `{tokens}`.'
        headers:
          items:
            $ref: '#/components/schemas/ToolKeyValue'
          type: array
          maxItems: 30
          description: >-
            request headers; values may contain `{tokens}`. authorization-style
            headers are stripped — use `auth` instead.
        params:
          items:
            $ref: '#/components/schemas/ToolKeyValue'
          type: array
          maxItems: 30
          description: query parameters; values may contain `{tokens}`.
        body:
          type: string
          maxLength: 16000
          default: ''
          description: request body for `POST`; may contain `{tokens}`.
        timeoutMs:
          type: integer
          maximum: 30000
          minimum: 100
          default: 5000
          description: 100–30000, default 5000.
        waitForResponse:
          type: boolean
          default: true
          description: >-
            for `during_call` tools: whether the model waits for the result
            before speaking.
        auth:
          $ref: '#/components/schemas/ToolAuthInput'
          description: >-
            the credential, write-only: `{type: none|bearer|api_key|basic,
            token, headerName, username, password}`.
        llmParams:
          items:
            $ref: '#/components/schemas/ToolLlmParam'
          type: array
          maxItems: 20
          description: >-
            for `during_call` tools: the arguments the model supplies. each
            becomes a `{name}` token.
        outputs:
          items:
            $ref: '#/components/schemas/ToolOutput'
          type: array
          maxItems: 20
          description: >-
            values the tool exposes: each `name` is a JSON key looked for
            anywhere in the response; `path` pins it to one dotted location
            instead. variables read them via `toolOutput`.
        output:
          anyOf:
            - $ref: '#/components/schemas/ToolLegacyOutput'
            - type: 'null'
      type: object
      title: ToolConfigInput
    ToolConfig:
      properties:
        action:
          $ref: '#/components/schemas/AgentToolAction'
        performedAction:
          $ref: '#/components/schemas/AgentToolPerformedAction'
        curl:
          type: string
          default: ''
        method:
          $ref: '#/components/schemas/AgentToolHttpMethod'
        url:
          type: string
        headers:
          items:
            $ref: '#/components/schemas/ToolKeyValue'
          type: array
        params:
          items:
            $ref: '#/components/schemas/ToolKeyValue'
          type: array
        body:
          type: string
        timeoutMs:
          type: integer
        waitForResponse:
          type: boolean
        auth:
          $ref: '#/components/schemas/ToolAuth'
        llmParams:
          items:
            $ref: '#/components/schemas/ToolLlmParam'
          type: array
        outputs:
          items:
            $ref: '#/components/schemas/ToolOutput'
          type: array
      type: object
      required:
        - action
        - performedAction
        - method
        - url
        - headers
        - params
        - body
        - timeoutMs
        - waitForResponse
        - auth
        - llmParams
        - outputs
      title: ToolConfig
      description: >-
        Server-constructed (``serialization_alias``), see
        :class:`AgentToolAuthView`.
    AgentToolAction:
      type: string
      enum:
        - get
        - post
        - perform
      title: AgentToolAction
      description: What the tool does when it runs. ``perform`` is a platform action.
    AgentToolPerformedAction:
      type: string
      enum:
        - end_call
        - transfer_call
      title: AgentToolPerformedAction
      description: The platform actions a ``perform`` tool can carry out.
    AgentToolHttpMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      title: AgentToolHttpMethod
    ToolKeyValue:
      properties:
        name:
          type: string
          maxLength: 128
        value:
          type: string
          maxLength: 2048
          default: ''
      type: object
      required:
        - name
      title: ToolKeyValue
    ToolAuthInput:
      properties:
        type:
          $ref: '#/components/schemas/AgentToolAuthType'
          default: none
          description: >-
            `none`, `bearer` (`Authorization: Bearer {token}`), `api_key`
            (`{headerName}: {token}`) or `basic` (`username` / `password`).
        token:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          description: >-
            the secret for `bearer` / `api_key`. on update: omit to keep the
            stored one, empty string to clear.
        headerName:
          type: string
          maxLength: 128
          default: X-API-Key
          description: the header for `api_key`; default `X-API-Key`.
        username:
          type: string
          maxLength: 2048
          default: ''
          description: for `basic`.
        password:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          description: for `basic`. write-only.
      type: object
      title: ToolAuthInput
      description: >-
        Write side of the endpoint's auth. ``token`` / ``password`` are the

        secret: sent on create, and on patch only when changing it (omitted
        keeps

        the stored one, an empty string clears it).
    ToolLlmParam:
      properties:
        id:
          type: string
          maxLength: 64
          default: ''
        name:
          type: string
          maxLength: 64
        type:
          $ref: '#/components/schemas/AgentToolParamType'
          default: string
        description:
          type: string
          maxLength: 500
          default: ''
        required:
          type: boolean
          default: true
      type: object
      required:
        - name
      title: ToolLlmParam
    ToolOutput:
      properties:
        name:
          type: string
          maxLength: 65
          default: ''
        path:
          type: string
          maxLength: 256
          default: ''
      type: object
      title: ToolOutput
      description: >-
        One value the tool exposes: ``name`` is the JSON key found anywhere in

        the response (written ``$name`` in the dashboard); ``path`` optionally
        pins

        it to a dotted location instead. A blank name is a row left empty.
    ToolLegacyOutput:
      properties:
        type:
          type: string
          maxLength: 256
          default: ''
        data:
          type: string
          maxLength: 65
          default: ''
      type: object
      title: ToolLegacyOutput
      description: >-
        The single-output shape older clients and rows use (``type`` = path,

        ``data`` = ``$variable``). Accepted on input and folded into
        ``outputs``.
    ToolAuth:
      properties:
        type:
          $ref: '#/components/schemas/AgentToolAuthType'
          default: none
        headerName:
          type: string
          default: X-API-Key
        username:
          type: string
          default: ''
        hasSecret:
          type: boolean
          default: false
          description: >-
            whether a credential is stored. the credential itself is never
            returned.
      type: object
      title: ToolAuth
      description: >-
        Read side: never the secret, only whether one is stored.


        Server-constructed, so the camelCase wire names are
        ``serialization_alias``

        (the constructor keeps the real field names) — as the other read models
        do.
    AgentToolAuthType:
      type: string
      enum:
        - none
        - bearer
        - api_key
        - basic
      title: AgentToolAuthType
    AgentToolParamType:
      type: string
      enum:
        - string
        - number
        - integer
        - boolean
      title: AgentToolParamType
      description: JSON-Schema scalar types a model-supplied argument can be declared as.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        your rumik api key, e.g. `rk_live_...`. create one in the rumik
        dashboard.

````