REST handler spec
One HTTP call, described once. The Oydin agent fills the parameters from the conversation.
Fields
| Field | Required | Description |
|---|---|---|
kind | yes | "rest". Fixed at creation. |
name | yes | Up to 60 characters. Becomes part of the tool name. |
description | yes | What the call does and when to use it (up to 500). The agent reads this. |
method | yes | GET, POST, PUT, PATCH or DELETE. |
url | yes | https URL template. {param} placeholders are URL-encoded. |
params_schema | no | JSON Schema, type: object. Every placeholder must appear in properties. |
auth_header | no | Header name, e.g. X-Api-Key. |
auth_secret | no | Header value. Write-only, encrypted. Send "" to remove. |
How parameters map to the request
- Parameters named in the URL fill the placeholders (and are required).
- For
GET/DELETEthe remaining parameters become the query string. - For
POST/PUT/PATCHthe remaining parameters are sent as a JSON body.
Example
POST /api/connectors/
{
"kind": "rest",
"name": "Stock level",
"description": "Returns how many units of a product are in stock. Use when the user asks about inventory.",
"method": "GET",
"url": "https://erp.example.com/items/{sku}/stock",
"params_schema": {
"type": "object",
"properties": {
"sku": {"type": "string", "description": "Product SKU"},
"warehouse": {"type": "string"}
},
"required": ["sku"]
},
"auth_header": "X-Api-Key",
"auth_secret": "k_live_…"
}
The agent calling it with sku=A-1, warehouse=main sends GET https://erp.example.com/items/A-1/stock?warehouse=main.
Response
The agent receives {"status": 200, "body": …}. JSON is parsed; other content is passed as text. Bodies are truncated to 20,000 characters. Timeout is 10 seconds, redirects are not followed, network errors come back as {"error": "Timeout"}.
Test it
POST /api/connectors/{id}/test/
{"args": {"sku": "A-1"}}
{"ok": true, "error": "", "result": {"status": 200, "body": {"qty": 4}}, ...}
Private, local and non-https addresses are rejected with
private_address / only_https. Limit: 20 connectors per business.