Jelliu API documentation

curl -X PATCH https://api.jelliu.co/api/agents/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/tools/7b0e4f3a-1c2d-4e5f-8a9b-0c1d2e3f4a5b \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "description": "Consulta el estado y la fecha estimada de entrega de un pedido. Úsala en cuanto el cliente dé un número de pedido; no la uses para devoluciones.",
  "responseTimeoutSecs": 30
}'

{
  "data": {
    "id": "7b0e4f3a-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
    "tenant_id": "2d9f6c1e-3b4a-4c5d-9e8f-7a6b5c4d3e2f",
    "agent_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "name": "consultar_pedido",
    "description": "Consulta el estado y la fecha estimada de entrega de un pedido. Úsala en cuanto el cliente dé un número de pedido; no la uses para devoluciones.",
    "type": "webhook",
    "method": "GET",
    "url": "https://api.tiendaandina.co/v1/pedidos/{numero_pedido}",
    "headers": [],
    "path_params": [
      {
        "identifier": "numero_pedido",
        "type": "string",
        "description": "Número del pedido que menciona el cliente, solo dígitos",
        "value_type": "llm_prompt",
        "required": true
      }
    ],
    "query_params": [],
    "body_params": [],
    "auth_type": "none",
    "response_timeout_secs": 30,
    "tool_call_sound": "typing",
    "tool_call_sound_behavior": "auto",
    "dynamic_variable_assignments": [],
    "position": 0,
    "created_at": "2026-09-01T15:04:05.000Z",
    "updated_at": "2026-09-15T09:12:44.000Z"
  }
}

Partially updates a tool: only the fields you send change. Array fields (headers, pathParams, queryParams, bodyParams, dynamicVariableAssignments) and authConfig are replaced as a whole, not merged, so send the complete list. type cannot be changed. Sending authType: none erases the stored credentials; sending toolCallSound: null removes the waiting sound.

Checks run in this order: agent exists and is provisioned (409 AGENT_PROVISIONING), tool exists, a changed url (and any authConfig.tokenUrl) resolves to a public address, a new name does not collide with another tool of the agent.

Side effects. Rebuilds and pushes the agent’s full tool list to the voice engine. If the push fails, every column is restored to its previous value and the request answers 500. A changed description changes when the model decides to call the tool from the next conversation on. The mutation is written to the audit log.

Idempotency. Safe to retry: sending the same body again produces the same tool (only updated_at moves).

Webhook events. audit.log_recorded for endpoints subscribed to it. See Webhooks.

Access

Required scope: write.
Rate limit: Configuration mutations — 10 requests/min per workspace, shared with other agent configuration writes, in addition to the General API limit. See Rate limits.
Plan: Available on every plan.

Partially updates a tool: only the fields you send change. Array fields (`headers`, `pathParams`, `queryParams`, `bodyParams`, `dynamicVariableAssignments`) and `authConfig` are replaced as a whole, not merged, so send the complete list. `type` cannot be changed. Sending `authType: none` erases the stored credentials; sending `toolCallSound: null` removes the waiting sound. Checks run in this order: agent exists and is provisioned (`409 AGENT_PROVISIONING`), tool exists, a changed `url` (and any `authConfig.tokenUrl`) resolves to a public address, a new `name` does not collide with another tool of the agent. **Side effects.** Rebuilds and pushes the agent's full tool list to the voice engine. If the push fails, every column is restored to its previous value and the request answers 500. A changed `description` changes when the model decides to call the tool from the next conversation on. The mutation is written to the audit log. **Idempotency.** Safe to retry: sending the same body again produces the same tool (only `updated_at` moves). **Webhook events.** `audit.log_recorded` for endpoints subscribed to it. See [Webhooks](/webhooks). **Access** - **Required scope:** `write`. - **Rate limit:** Configuration mutations — 10 requests/min per workspace, shared with other agent configuration writes, in addition to the General API limit. See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Path parameters

agentIdstringRequiredformat: "uuid"

UUID of the agent that owns the tool.

toolIdstringRequiredformat: "uuid"

UUID of the tool to update.

Request

This endpoint expects an object.

namestringOptionalformat: "^[a-z][a-z0-9_]*$"1-100 characters

New function name; must not collide with another tool of the agent (409).

descriptionstringOptional5-2000 characters

New instruction for when the model should call the tool.

methodenumOptional

New HTTP method. Body parameters only travel with POST, PUT and PATCH.

urlstringOptionalformat: "uri"<=2000 characters

New endpoint. When it changes, it is re-checked against private addresses through DNS.

headerslist of objectsOptional

Full replacement header list.

pathParamslist of objectsOptional

Full replacement path parameter list.

queryParamslist of objectsOptional

Full replacement query parameter list.

bodyParamslist of objectsOptional

Full replacement body parameter list.

authTypeenumOptional

New authentication scheme; none also erases stored credentials.

authConfigobjectOptional

Credentials matching authType. Encrypted at rest (AES-256-GCM, bound to the workspace), never returned by any endpoint and excluded from agent version snapshots. On update the whole object is replaced, and blank strings count as absent. Not currently part of the configuration pushed to the voice provider.

responseTimeoutSecsintegerOptional1-120

New response timeout in seconds.

toolCallSoundenumOptional

New waiting sound, or null to remove it.

toolCallSoundBehaviorenumOptional

When the sound plays.

dynamicVariableAssignmentslist of objectsOptional

Full replacement list of response-to-variable mappings (stored only).

positionintegerOptional>=0

New sort key.

Response

The updated tool.

dataobject

A webhook tool as returned by the API. Keys are snake_case (the request bodies use camelCase). auth_config is never returned.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

Idempotency. Safe to retry: sending the same body again produces the same tool (only updated_at moves).

Webhook events. audit.log_recorded for endpoints subscribed to it. See Webhooks.

Access

Required scope: write.
Rate limit: Configuration mutations — 10 requests/min per workspace, shared with other agent configuration writes, in addition to the General API limit. See Rate limits.
Plan: Available on every plan.