Skip to main content

External API

The External API allows external systems to call Siesta AI directly. It is intended for customer applications, internal portals, automation backends, and integration services that need to create agents, call an agent, upload files, manage tasks, list available connections, or read audit data.

This page describes the API from a product and integration perspective. For a complete machine-readable endpoint reference, use the API documentation exposed by the Siesta AI application.

The External API is different from the Rest API connection. The Rest API connection lets Siesta AI call another HTTP API. The External API lets another system call Siesta AI.

Endpoint Reference​

Use the External API Reference to browse every endpoint from the OpenAPI specification, inspect parameters and schemas, and copy example requests with placeholder authentication headers.

Typical Use Cases​

  • Embed a Siesta AI agent into an internal application or customer portal.
  • Send a user question to an agent and store the returned conversationId.
  • Upload a temporary file and send it to an agent as context.
  • Create or update tasks from a CRM, ticketing system, or workflow engine.
  • Start a realtime voice or streaming session with an agent.
  • Export audit log records for compliance or operational monitoring.
  • List available task workspaces, data source collections, or connections before creating an integration flow.

Authentication​

External API calls are authenticated with an organization API key.

Required headers:

X-Api-Key: <api-key>
X-Org-Id: <organization-id>

API keys are managed in Organization -> Api Keys. Treat API keys as backend secrets. Do not expose them in browser-only code, public mobile clients, or client-side widgets where users can inspect network traffic.

Recommended practices:

  • Use a separate API key for each integration.
  • Use different keys for development, staging, and production.
  • Rotate keys regularly and immediately after a suspected leak.
  • Delete keys that are no longer used.
  • Review the audit log after making changes to production integrations.

API Basics​

The current External API base path is:

/api/v1

Most endpoints use JSON request and response bodies. File upload and download endpoints use file payloads. Realtime communication uses a session creation request followed by a WebSocket connection.

Common conventions:

  • Resource identifiers are GUID values.
  • List endpoints support paging parameters such as offset and limit where available.
  • Some list endpoints also support search, sorting, and domain-specific filters.
  • Access is scoped to the organization associated with the API key.
  • Agent behavior still depends on the agent configuration, model connection, data collections, tools, organization security settings, and connection governance rules.

Agents​

Agents are the main entry point for AI-powered integration.

List Agents​

GET /api/v1/Agent

Use this endpoint to list agents available to the integration. The response includes fields such as agent ID, name, creation date, public status, icon, icon color, and model name.

Use this when an external application lets users choose an agent or when an integration needs to validate that a configured agent still exists.

Create Agent​

POST /api/v1/Agent

Creates a new agent from an external system.

The create request can define product-relevant agent configuration such as:

  • name and description,
  • system message and initial message,
  • model name and model parameters,
  • reasoning effort,
  • data source collections,
  • shared and private tools,
  • sub-agents,
  • public chat and widget settings,
  • feedback and file upload settings.

Use this endpoint when an external admin flow or provisioning process needs to create agents programmatically.

Create Agent Response​

POST /api/v1/Agent/{agentId}/response

Creates a new conversation with the selected agent, sends the input message, and returns the agent output together with the conversationId.

Example request:

{
  "input": "Summarize the uploaded document and list the main risks.",
  "fileIds": ["1f4c0e12-4d16-4d7a-bc41-72a69f51d1d2"]
}

Example response:

{
  "output": "The document describes...",
  "conversationId": "9a53f66d-18f3-42ec-a5ef-920e55f6dcb4"
}

Use fileIds only for files that were uploaded through the External API file endpoint.

Realtime Agent Sessions​

Realtime sessions are used for interactive or voice-oriented experiences where a client communicates with an agent through a WebSocket connection.

For the full product lifecycle, public/internal distinction, session limits, and safety expectations, see Realtime and Voice Conversations.

Create Realtime Session​

POST /api/v1/Agent/{agentId}/realtime-session

Creates a realtime session for an agent. The request can either reuse an existing conversationId or let the API create a new conversation automatically.

The response includes:

  • sessionId,
  • conversationId,
  • expiresAt,
  • WebSocket path,
  • supported input and output audio formats,
  • maximum session duration,
  • idle timeout,
  • provider model name.

Connect to Realtime WebSocket​

GET /api/v1/Agent/{agentId}/realtime

This endpoint expects a WebSocket request. The client passes the realtime conversationId and sessionId as query parameters.

Important behavior:

  • The realtime session is tied to a specific agent and conversation.
  • The client should reconnect by creating a new session when the previous session expires.
  • The client must respect the supported audio formats returned by the session creation endpoint.
  • Idle timeout and maximum session duration are enforced by the platform.

Files​

The File API handles temporary files used as context for agent requests.

Upload File​

POST /api/v1/File

Uploads a temporary file and returns:

  • file ID,
  • file name,
  • MIME type.

The current upload limit is 200 MB.

Download File​

GET /api/v1/File/{id}

Downloads a previously uploaded temporary file.

Uploaded files can be passed to POST /api/v1/Agent/{agentId}/response using fileIds. Uploading a file through this API does not automatically add it to a long-term knowledge base. Use data source collections for persistent knowledge management.

Data Source Collections​

Data source collections are long-term knowledge containers that can be attached to agents.

Available operations:

GET /api/v1/DataSourceCollection
GET /api/v1/DataSourceCollection/{id}
POST /api/v1/DataSourceCollection
PUT /api/v1/DataSourceCollection/{id}

Use data source collections when an external system needs to prepare or manage knowledge containers before assigning them to agents. A data source collection can later be used in agent configuration with settings such as maximum chunks and relevance threshold.

Connections​

GET /api/v1/Connection

The Connections endpoint lists connections available in the organization. It can be filtered by search, scope, and connection type.

The response includes:

  • connection ID,
  • connection name,
  • connection type,
  • creation date,
  • default status,
  • access mode.

Use this endpoint when an integration needs to discover which model connections, tools, or external system connections are available before creating or configuring agents.

Connection availability is affected by organization policy. If a connection type or function is disabled by governance settings, agents and workflows should not assume that it can be used.

Tasks​

The Task API lets external systems create and manage work items in Siesta AI.

Available operations:

GET /api/v1/Task
GET /api/v1/Task/{id}
POST /api/v1/Task
PUT /api/v1/Task/{id}

Tasks can include:

  • workspace,
  • summary,
  • status,
  • prompt,
  • assigned agent,
  • source agent,
  • source conversation,
  • icon.

Typical scenarios:

  • A CRM creates a task for an AI agent after a customer event.
  • A ticketing system sends an unresolved case to Siesta AI for summarization or next-step drafting.
  • A workflow engine updates task status after external approval.

Task execution and task review behavior depends on the selected workspace, assigned agent, and application configuration.

Workspaces​

GET /api/v1/Workspace

The Workspace API lists task workspaces. A workspace groups related tasks and can define a default agent.

The response includes:

  • workspace ID,
  • name,
  • default agent ID and name,
  • default agent icon and icon color,
  • auto-execution setting,
  • creation date.

Use this endpoint before creating tasks so the integration can place work into the correct workspace.

Audit Log​

The Audit Log API supports compliance, monitoring, and incident review.

Available operations:

GET /api/v1/AuditLog
GET /api/v1/AuditLog/{id}

The list endpoint supports filters such as date range, change type, user, and entity type. Audit records include information such as correlation ID, creation time, user, entity type, and change type. The detail endpoint includes changed properties with old and new values.

Audit log availability is affected by the organization's audit log retention settings.

Error Handling​

External clients should handle these common response categories:

  • 400 Bad Request - invalid input, unsupported parameter combination, or malformed payload.
  • 401 Unauthorized - missing or invalid authentication.
  • 403 Forbidden - authenticated caller does not have access to the requested operation.
  • 404 Not Found - resource does not exist or is not available in the current organization.
  • 429 Too Many Requests - usage is limited by rate, quota, or token budget controls when configured.
  • 500 Internal Server Error - unexpected server-side failure.

For long-running or user-facing integrations, show a clear fallback message and keep enough local context to retry safely.

Security and Governance​

External API integrations should follow the same governance expectations as internal Siesta AI usage.

Recommended controls:

  • Keep API keys on a trusted backend.
  • Restrict each integration to the minimum needed workflow.
  • Prefer separate agents for different integration contexts.
  • Use connection governance for tools that can read sensitive data or modify external systems.
  • Use approvals for actions that change business data.
  • Enable content safety and prompt shield settings for public or customer-facing integrations.
  • Monitor agent usage, tool executions, and audit logs after deployment.
  • Review token limits and cost controls before enabling high-volume automation.