API reference · Tools

Create a tool

POSThttps://goblins-call-api.onrender.com/v1/tools

Gives an agent an HTTP endpoint of yours to call. Switch it on by adding its ID to the agent’s toolIds, or by mentioning it as @name in the instructions.

Needs a workspace API key.

Body

agentIdstringOptional

The agent the tool is for. It cannot be changed afterwards.

namestringRequired1–128 chars

An identifier the model uses to ask for the tool, such as check_order_status. It is saved in lower case with anything but letters, digits and _ turned into _. Instructions mention it as @check_order_status.

descriptionstringRequiredup to 5,000 chars

What the tool does and when to use it. The model reads this to decide.

kindenumOptionalduring_call · before_call; default during_call

during_call tools are run by the model in the middle of a conversation. before_call tools run once as the call starts, and their response is added to the agent’s instructions.

methodenumOptionalGET · POST; default GET

The HTTP method of the request to your endpoint.

urlstringRequired

Your endpoint. Must be a public http(s) address; redirects are not followed. May contain {{placeholders}}.

paramsobject[]Optional

The arguments the model supplies, each { "key": "order_id", "value": "A-1042" }. value is an example shown to the model, and what is sent when the model leaves the argument out. Sent as the query string of a GET, or as the JSON body of a POST that has no body of its own.

headersobject[]Optional

Extra request headers, each { "key", "value" }. Values may contain {{placeholders}}.

bodystringOptional

A body template for a POST, with {{placeholders}}. Sent as JSON unless a Content-Type header says otherwise.

authenumOptionalnone · bearer · api_key · basic; default none

How the request authenticates to your endpoint.

authTokenstringOptional

The bearer token, API key or basic-auth password. Stored encrypted.

authKeyHeaderstringOptionaldefault X-API-Key

The header an api_key credential is sent in.

authUsernamestringOptional

The username for basic auth.

timeoutMsintegerOptional500–60,000; default 10,000

How long to wait for your endpoint. A request is cut off at 30 seconds whatever is set here.

outputsobject[]Optional

The fields your endpoint answers with, each { "name", "description" }, for your own reference in the studio.

sampleOutputstringOptional

An example response. The model is shown it so it knows what to expect back.

Errors

400

The body failed validation. details lists each field and what is wrong with it.

400URL_NOT_ALLOWED

The URL is not a public http(s) address.

404

No agent in your workspace has that ID.

Every request can also answer 401, 429 and 500: see Errors.

curl -X POST "https://goblins-call-api.onrender.com/v1/tools" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "ua_3f9a1c2b",
  "name": "check_order_status",
  "description": "Looks up an order by its number, which the caller reads out. Use it when the caller asks where their order is.",
  "kind": "during_call",
  "method": "GET",
  "url": "https://your-app.com/api/orders/{{order_id}}",
  "params": [
    {
      "key": "order_id",
      "value": "A-1042"
    }
  ],
  "auth": "bearer",
  "authToken": "YOUR_ENDPOINT_TOKEN",
  "timeoutMs": 5000
}'

Response · 201 Created

{
  "tool": {
    "id": "tool_5d2e8a41c07b",
    "userId": "usr_8c1d2e3f4a5b",
    "agentId": "ua_3f9a1c2b",
    "name": "check_order_status",
    "description": "Looks up an order by its number, which the caller reads out. Use it when the caller asks where their order is.",
    "kind": "during_call",
    "method": "GET",
    "url": "https://your-app.com/api/orders/{{order_id}}",
    "timeoutMs": 5000,
    "params": [{ "key": "order_id", "value": "A-1042" }],
    "headers": [],
    "auth": "bearer",
    "authToken": "…",
    "outputs": [{ "name": "status" }, { "name": "eta" }],
    "createdAt": "2026-10-11T08:20:03.000Z",
    "updatedAt": "2026-10-11T08:20:03.000Z"
  }
}