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 ​

Before you use the Headless API, confirm the following:

• You have a genie in Agent Studio.
• You've set up the genie's custom chat interface from the Agent Studio UI, including creating and attaching a genie client with either API key or OAuth 2.0 (PKCE) credentials. Refer to Genie clients in the Developer API if you provision the client programmatically instead of through the UI.
• Headless API is enabled for your workspace. Headless API is in private beta: if the custom chat interface option doesn't appear in your genie's chat interface settings, contact your Customer Success Manager to request access.
• Your builder role has the Custom chat interface privilege under Genie building. Refer to collaborator privileges for more information on configuring builder roles.

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 ​

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 ​

OAuth 2.0 PKCE authorization flow ​

OAuth clients authenticate end users through Workato Identity (id.workato.com) using the authorization code flow with PKCE. No client secret is required. Use the oauth_client_id returned when you create an OAuth genie client.

You must complete the following steps to use this authorization flow:

https://id.workato.com/oauth/authorize?response_type=code
  &client_id=<oauth_client_id>
  &redirect_uri=<your_redirect_url>
  &scope=openid profile email
  &state=<random_state>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256

curl -X POST https://id.workato.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<oauth_client_id>" \
  -d "redirect_uri=<your_redirect_url>" \
  -d "code=<authorization_code>" \
  -d "code_verifier=<code_verifier>"

curl -X POST https://id.workato.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=<oauth_client_id>" \
  -d "refresh_token=<refresh_token>"

The redirect URL must match the oauth_redirect_url registered on the client. Perform the code exchange in the preceding steps from a same-origin backend rather than directly in the browser. This ensures the flow is free of cross-origin (CORS) concerns and keeps token handling server-side.

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. The maximum file size is 20 MB.

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
• A genie supports a single attached client. The client-to-genie relationship is 1:1: attaching a second client returns a 409 conflict. Detach the existing client first to re-point it.