Developers / Tools

Create an OpenAPI tool

POST https://api.echonova.ai/v1/tools/openapi

Imports an OpenAPI document, inline or from a public url, as one tool with an operation for each endpoint. Auth connections and secret headers are referenced by id; plain values that look like credentials are refused. The import is indexed before the call answers. Send an Idempotency-Key to retry safely. At most 5 calls a minute per key. Secrets are referenced by id from GET /v1/secrets; their values can only be entered in the portal vault. Free. Needs the tools:write scope on the key.

Headers

Authorization string Required

Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.

Idempotency-Key string Optional

Optional. Repeat the same key within 24 hours to retry safely: the first result comes back and nothing is made twice. A new request needs a new key.

Request body

application/json

spec object Optional

The OpenAPI document as JSON, up to 5 MB. Send exactly one of spec or url.

url string Optional

Public https URL of the OpenAPI document. Send exactly one of spec or url.

Up to 2000 characters
name string Required

Tool name, unique in the workspace.

1 to 120 characters
description string Optional

What the API is for.

Up to 500 characters
baseUrlOverride string Required

The server the tool calls.

Up to 2000 characters
includeOperations array of string Optional

Operation names to import. Leave it out for all.

authConnectionId string Optional

Auth connection id sent on every call. List ids with GET /v1/auth-connections. Leave it out for a public API.

operationEdits array of objects Optional

Per-operation description, fixed values and auth.

Response

200 application/json Every response uses this envelope.

data object

The result.

success boolean

true for a successful call.

statusCode integer

Repeats the HTTP status.

errorMessage string or null

null on success.

Errors

Same envelope, with success false and data null. All errors

POST /v1/tools/openapi

curl -X POST "https://api.echonova.ai/v1/tools/openapi" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Orders API","baseUrlOverride":"https://api.example.com"}'

{
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "name": "Order lookup",
    "type": "webhook",
    "description": "Finds an order by its number.",
    "createdAt": "2026-11-01T10:00:00.000Z",
    "updatedAt": "2026-11-01T10:00:00.000Z",
    "webhook": {
      "url": "https://api.example.com/orders/{orderId}",
      "method": "GET",
      "timeoutMs": 10000,
      "connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
      "parameters": [
        {
          "location": "header",
          "name": "orderId",
          "dataType": "string",
          "required": true,
          "description": "Finds an order by its number.",
          "valueType": "llm",
          "secretId": "YOUR_SECRET_ID"
        }
      ]
    },
    "openapi": {
      "apiTitle": "Orders API",
      "operationCount": 12,
      "status": "ready",
      "baseUrl": "https://api.example.com",
      "includeOperations": [
        "getOrder"
      ],
      "authConnectionId": "YOUR_AUTH_CONNECTION_ID",
      "error": null
    },
    "integration": {
      "provider": "slack",
      "key": "add_reaction"
    }
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}