API reference · Tools

Update tool

patchhttps://api.integrable.cloud/api/tools/{tool_id}

Authentication: Bearer token
Retries: Idempotency-Key
Body: application/json
Version: 2026-09-03

Path parameters

tool_idstring (uuid)required

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

ToolUpdate

auth_kindstring | null
One of: none, bearer, header, basic, query
auth_namestring | null
Up to 128 characters
auth_secretstring | null
Up to 4096 characters
auth_usernamestring | null
Up to 255 characters
body_modestring | null
One of: none, arguments, template
body_templateany
bot_idstring (uuid) | null
descriptionstring | null
10–1024 characters
display_namestring | null
Up to 128 characters
headersmap of string | null
idempotentboolean | null
input_schemaobject | null
is_enabledboolean | null
max_attemptsinteger | null
≥ 1 and ≤ 5
max_response_bytesinteger | null
≥ 1024 and ≤ 4194304
max_response_charsinteger | null
≥ 200 and ≤ 100000
methodstring | null
One of: GET, HEAD, POST, PUT, PATCH, DELETE
namestring | null
Up to 64 characters·Pattern: ^[a-zA-Z0-9_-]{1,64}$
query_templatemap of string | null
response_pathstring | null
Up to 255 characters
timeout_msinteger | null
≥ 1000 and ≤ 60000
url_templatestring | null
Up to 2048 characters

Responses

200OKapplication/json
ToolResponse
- auth_kindstringrequired
- auth_namestring | nullrequired
- auth_usernamestring | nullrequired
- body_modestringrequired
- bot_idstring (uuid) | nullrequired
- 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.

Example request

curl

curl -X PATCH "https://api.integrable.cloud/api/tools/$TOOL_ID" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_kind": "none"
  }'

Set INTEGRABLE_API_KEY and the path variables first. The same call from the TypeScript or Python SDK takes the same fields.

Example response

200 OK · application/json

{
  "auth_configured": false,
  "auth_kind": "string",
  "auth_name": "string",
  "auth_username": "string",
  "body_mode": "string",
  "body_template": "string",
  "bot_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
  "call_count": 20,
  "created_at": "2026-09-03T09:30:00Z",
  "description": "string",
  "display_name": "string",
  "error_count": 20,
  "headers": {},
  "id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
  "idempotent": true,
  "input_schema": {},
  "is_enabled": true,
  "last_called_at": "2026-09-03T09:30:00Z",
  "last_error": "string",
  "last_error_at": "2026-09-03T09:30:00Z",
  "max_attempts": 0,
  "max_response_bytes": 0,
  "max_response_chars": 0,
  "method": "string",
  "name": "string",
  "org_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
  "query_template": {},
  "response_path": "string",
  "timeout_ms": 0,
  "updated_at": "2026-09-03T09:30:00Z",
  "url_template": "string"
}

Generated from the schema above — the shape is exact, the values are placeholders.

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-bot limit on top.

More Tools endpoints

Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.