Headless API ​

The custom chat interface lets you connect your genie to any application you build and control. Your application talks to your genie directly over a REST API, called a Headless API, instead of routing users through Slack, Microsoft Teams, or Workato GO. The custom chat interface includes API endpoints to manage conversations and send and receive genie messages. This API is separate from the Agent Studio Developer API, which lets you create, configure, and maintain genies.

Headless API prerequisites ​

Headless API has the following prerequisites:

• A client role with the following permissions:
  • Genies: Read and write permissions for CRUD operations on genies, skills, knowledge bases, user groups, and guardrails
  • Genie client: Read and write permissions for CRUD operations on clients and client-genie assignments
• An API client attached to the preceding client role
• A folder ID where the genie is stored. Use the following API endpoint to obtain your folder ID:

curl -s "https://app.workato.com/api/folders" \
  -H "Authorization: Bearer $DEV_API_TOKEN"

Headless API base URLs ​

Headless API is available in all data centers where Agentic is supported. The base URLs follow the same per-data-center scheme as the app host. For example:

Refer to the data center overview for more information.

Authentication ​

The Headless API provides two access methods that address different integration scenarios. Authentication is enforced at the API gateway layer, with no runtime dependency on the Workato system. Token configuration is synced to the gateway asynchronously and verification is performed in-process. API tokens are per-environment. This means you must have a unique API token for each environment. Refer to How to generate an API token for more information.

Headless API supports the following access methods:

API key:

Authorization: Bearer <api_key>
X-IDP-User-Id: <idp_user_id>

OAuth 2.0 (PKCE):

Authorization: Bearer <access_token>

Authorization methods comparison ​

Refer to the following authorization method comparison and use case recommendation tables to determine which authorization method to use:

Recommended authorization method by scenario ​

Quick reference ​

List conversations ​

Retrieve a list of the authenticated user's conversations. Results are listed by the created_at timestamp in descending order.

GET /api/v1/genies/:genie_handle/chat/conversations

URL parameters ​

Query parameters ​

Response ​

Create a conversation ​

Create a new conversation with the genie.

POST /api/v1/genies/:genie_handle/chat/conversations

URL parameters ​

Response ​

Get a conversation ​

Retrieve the details and current state of a conversation.

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id

URL parameters ​

Response ​

Get messages ​

Retrieve message history for a conversation. Results are listed by the created_at timestamp in descending order.

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messages

URL parameters ​

Query parameters ​

Response ​

Send a message ​

Send a user message and receive a real-time stream of events as the genie processes and responds.

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messages

URL parameters ​

Payload ​

Response ​

When stream is false, returns HTTP 202 with the following body:

When stream is true, the response is a stream of Server-Sent Events. The stream closes when the genie finishes processing, indicated by the processing.finished event.

Reconnect to a stream ​

Reopen the SSE stream for a specific genie run. Use this to recover events after a disconnection. Pass the ID of the last successfully received event in the Last-Event-ID header.

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/genie-runs/:genie_run_id

URL parameters ​

Headers ​

Response ​

The response is a stream of Server-Sent Events.

Get events ​

Retrieve recent events. Use this as a fallback to manually fetch missed events after a disconnection. Events are returned oldest first and are available for 24 hours.

GET /api/v1/genies/:genie_handle/chat/conversations/events

URL parameters ​

Query parameters ​

Response ​

Approve or reject a skill ​

Approve or reject a skill confirmation request. Use this when the genie emits a skill.confirmation_required event.

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/skill_approval/:call_id

URL parameters ​

Payload ​

Get a runtime connection link ​

Get an authentication link for a runtime connection. Use this when the genie emits a runtime_connection.auth_required event.

POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/link

URL parameters ​

Response ​

Reject a runtime connection ​

Reject a runtime connection request.

POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/reject

URL parameters ​

Payload ​

Upload a file ​

Upload a file to attach to a subsequent message. Returns a file_id to pass in the file_id parameter of Send a message.

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/upload

URL parameters ​

Payload ​

Response ​

SSE events ​

You can send a message with stream: true to get a response with a stream of SSE covering the full lifecycle of the genie's response.

Events are persisted for 24 hours and are retrievable through the Get events endpoint.

Base event shape ​

Every event shares the following base fields:

Event types ​

Limitations ​

Headless API endpoints have the following limitations:

• Action Board isn't supported
• App Events aren't supported