DocsAPI reference

Create tool

post/api/tools
Authentication
Bearer token
Body
application/json
Version
2026-09-03

Headers#

  • Idempotency-Keystring

    A unique key of your choosing, so this request can be retried safely. The first request with a given key executes; every replay returns that first response unchanged, with Idempotent-Replay: true set.

    Generate one key per action, not per session - reusing a key with a different body is refused with 422 rather than silently replaying the wrong answer. Keys are remembered for 24 hours. A request that failed releases its key, so a retry after fixing the payload runs normally.

    Up to 255 characters

Request body#

application/json · required

ToolCreate

  • descriptionstringrequired

    10–1024 characters

  • namestringrequired

    1–64 characters·Pattern: ^[a-zA-Z0-9_-]{1,64}$

  • url_templatestringrequired

    1–2048 characters

  • agent_idstring (uuid) | null
  • auth_kindstring

    One of: none, bearer, header, basic, query·Default: none

  • auth_namestring | null

    Up to 128 characters

  • auth_secretstring | null

    Up to 4096 characters

  • auth_usernamestring | null

    Up to 255 characters

  • body_modestring

    One of: none, arguments, template·Default: arguments

  • body_templateany
  • display_namestring | null

    Up to 128 characters

  • headersmap of string
  • idempotentboolean | null
  • input_schemaobject
  • is_enabledboolean

    Default: true

  • max_attemptsinteger

    Default: 2·≥ 1 and ≤ 5

  • max_response_bytesinteger

    Default: 262144·≥ 1024 and ≤ 4194304

  • max_response_charsinteger

    Default: 8000·≥ 200 and ≤ 100000

  • methodstring

    One of: GET, HEAD, POST, PUT, PATCH, DELETE·Default: GET

  • query_templatemap of string
  • response_pathstring | null

    Up to 255 characters

  • timeout_msinteger

    Default: 10000·≥ 1000 and ≤ 60000

Responses#

  • 201Createdapplication/json

    ToolResponse

    • agent_idstring (uuid) | nullrequired
    • auth_kindstringrequired
    • auth_namestring | nullrequired
    • auth_usernamestring | nullrequired
    • body_modestringrequired
    • call_countintegerrequired
    • created_atstring (date-time)required
    • descriptionstringrequired
    • display_namestring | nullrequired
    • error_countintegerrequired
    • headersobjectrequired
    • idstring (uuid)required
    • idempotentboolean | nullrequired
    • input_schemaobjectrequired
    • is_enabledbooleanrequired
    • last_called_atstring (date-time) | nullrequired
    • last_errorstring | nullrequired
    • last_error_atstring (date-time) | nullrequired
    • max_attemptsintegerrequired
    • max_response_bytesintegerrequired
    • max_response_charsintegerrequired
    • methodstringrequired
    • namestringrequired
    • org_idstring (uuid)required
    • query_templateobjectrequired
    • response_pathstring | nullrequired
    • timeout_msintegerrequired
    • updated_atstring (date-time)required
    • url_templatestringrequired
    • auth_configuredboolean

      Default: false

    • body_templateany
    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

  • 422Validation error

    The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • validation_error · 422 — The payload was well-formed JSON but failed schema validation.
  • unauthenticated · 401 — The request carried no API key, or one the API could not verify.
  • forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
  • idempotency_key_reused · 422 — This `Idempotency-Key` was used before, for a request with a different body.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Tools endpoints#

Something unclear or missing? Tell us and we’ll fix it.