Headers and content types

Use the headers and body type declared by each operation. Operade rejects ambiguous or malformed input instead of guessing how a payload should be interpreted.

Common request headers#

API-key operations use Authorization: Bearer YOUR_API_KEY. JSON requests use Content-Type: application/json, and callers can send Accept: application/json. Browser session mutations use the cx_session cookie plus X-CX-Request: 1. The request-intent header is not a substitute for authentication.

Telegram's provider callback uses X-Telegram-Bot-Api-Secret-Token. That header belongs only to the provider receiver; customers should not attach it to normal API calls. Post-call delivery uses a response-facing signature header documented in Webhook signatures.

JSON bodies#

Most create, update, preview, execute, configuration, and action requests accept application/json. Send actual JSON types: do not encode booleans or numbers as strings unless the operation schema says the field is a string. Unknown fields may be rejected. A successful response with a body is JSON unless the operation page states otherwise.

curl --request PATCH 'https://operade.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/agents/YOUR_AGENT_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Support agent"}'

File imports#

Procedure import and Knowledge file upload use multipart/form-data with a file part. Let the HTTP client create the multipart boundary; manually setting only the media type often produces an invalid request. Knowledge URL import is JSON, not multipart, because it submits a URL rather than file bytes.

Empty responses and errors#

HTTP 204 has no response body and should not be parsed as JSON. Error responses use the JSON error envelope even when the successful path has no body. Preserve the HTTP status and error.code for recovery.

See API introduction, API errors, and the exact operation page before constructing a request.