Oydin for developers

REST handler spec

One HTTP call, described once. The Oydin agent fills the parameters from the conversation.

Fields

FieldRequiredDescription
kindyes"rest". Fixed at creation.
nameyesUp to 60 characters. Becomes part of the tool name.
descriptionyesWhat the call does and when to use it (up to 500). The agent reads this.
methodyesGET, POST, PUT, PATCH or DELETE.
urlyeshttps URL template. {param} placeholders are URL-encoded.
params_schemanoJSON Schema, type: object. Every placeholder must appear in properties.
auth_headernoHeader name, e.g. X-Api-Key.
auth_secretnoHeader value. Write-only, encrypted. Send "" to remove.

How parameters map to the request

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.