Developers / Tools
Preview an OpenAPI import
https://api.echonova.ai/v1/tools/openapi/previewReads an OpenAPI document, inline or from a public url, and lists the operations a tool would import. Nothing is saved. At most 5 calls a minute per key. Free. Needs the tools:write scope on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Request body
application/json
The OpenAPI document as JSON, up to 5 MB. Send exactly one of spec or url.
Public https URL of the OpenAPI document. Send exactly one of spec or url.
The server the tool calls, replacing the document servers. Required on create.
Response
200 application/json Every response uses this envelope.
The result.
Title of the document.
How many operations the document has.
Things the import would skip or change.
The server the document declares, or an empty string.
The operations a tool would import.
Operation name, as operationEdits uses it.
HTTP method.
Path in the document.
What the operation does.
Whether the operation changes data.
The operation parameters.
Parameter name.
path, query, header or cookie.
Whether the operation needs it.
The type of value it takes.
The top-level request body fields.
Body field name.
The type of value it takes.
Whether the operation needs it.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. A parameter or fieldValues entry with valueType constant has a name that looks like a credential, such as Authorization, token, api key or cookie. The message names the field and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. A constant value starts with Bearer, Basic, Token or Digest, or has the shape of a JWT. The message names the field and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. The webhook url or baseUrlOverride has a query key that looks like a credential. The message names the key and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. A credential-like key is hidden in the query or fragment of the webhook url or baseUrlOverride.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. The document url is not https, or points at a loopback, private or link-local address, or is not a URL.
Fix. Send a public https URL, or send the document inline as spec.
When. The document url carries a user name or password.
Fix. Send the URL without them, and use a secret header or an auth connection.
When. baseUrlOverride is not https, or points at a loopback, private or link-local address, or is not a URL.
Fix. Send a public https URL.
When. baseUrlOverride carries a user name or password.
Fix. Send the URL without them, and use a secret header or an auth connection.
When. The document could not be read as an OpenAPI document. The text names what is wrong, so it varies.
Fix. Fix the document as the message says, then preview it again.
When. The body has both spec and url, or neither.
Fix. Send exactly one of them.
When. The inline spec is over 5 MB.
Fix. Send it as a public url instead.
When. The document at url is over 5 MB.
Fix. Send a smaller document.
When. The url did not answer in time or could not be read.
Fix. Check that the url is public and answers quickly, or send the document inline.
When. The url answered with an error status; the message names it.
Fix. Check the url.
When. The url answered with something that is not a JSON document.
Fix. Send the JSON form of the document.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the tools:write scope. agents:write does not give it.
Fix. Edit the key and give it the tools:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage tools and Manage developer API permissions. It is checked on every call.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. The JSON body of an OpenAPI preview or create is over 6 MB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send the document as a public url instead of inline.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
When. The key made more than 5 requests to this endpoint in 60 seconds; a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl -X POST "https://api.echonova.ai/v1/tools/openapi/preview" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"apiTitle": "Orders API",
"operationCount": 12,
"warnings": [
"Skipped 2 operations without an operationId"
],
"baseUrl": "https://api.example.com",
"operations": [
{
"name": "getOrder",
"method": "GET",
"path": "/orders/{orderId}",
"description": "Find an order.",
"mutating": false,
"parameters": [
{
"name": "orderId",
"location": "path",
"required": true,
"type": "string"
}
],
"bodyFields": [
{
"name": "quantity",
"type": "integer",
"required": false
}
]
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}