Skip to main content

Getting Started

The Siesta AI REST API lets your backend create, read, and update selected Siesta AI resources from your own systems. Use it for server-side integrations, admin workflows, reporting, and application features that need a stable HTTP contract.

The REST API is inbound: your system calls Siesta AI. This is different from the REST API connection, which is outbound, letting Siesta AI call another HTTP API.

Common integrations:

  • Send a user question to an agent and store the returned conversationId.
  • Provision or list agents from an admin backend or customer portal.
  • Upload a temporary file and pass 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.

Base URL​

Use the production API base URL:

https://api.siesta.ai

Endpoint paths in the reference include the /api/v1 prefix. Combine the base URL with the path shown on each endpoint.

First Request​

Start with a read-only endpoint, such as listing agents or tasks. Keep API credentials on your backend and send the required headers with each request.

curl -X GET "https://api.siesta.ai/api/v1/Agent?Limit=10" \
  -H "X-Api-Key: <api-key>" \
  -H "X-Org-Id: <organization-id>"

Use the REST API Reference for exact paths, query parameters, request bodies, response schemas, and examples generated from the current OpenAPI contract.

Pagination And Errors​

List endpoints commonly accept pagination parameters such as Offset and Limit when they are present in the OpenAPI contract. Responses and error shapes are documented per endpoint in the reference.

Handle these status families consistently:

  • 2xx: request succeeded.
  • 4xx: request was rejected because of input, authentication, authorization, rate limit, or missing resource.
  • 5xx: Siesta AI could not complete the request.

Authentication​

Every REST API request must include both headers:

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

X-Api-Key identifies the calling integration. X-Org-Id scopes the request to one Siesta AI organization. A valid key without the matching organization context will still fail for resources outside that scope.

Manage API keys in the Siesta AI app under Organization → API Keys. Use a separate key per integration and per environment, and delete keys that are no longer used.

The interactive reference uses placeholders in code samples. Replace them in your backend or local test tool. Do not expose production API keys in frontend code.

Trusted Execution Only​

Use API keys only from trusted server-side code:

  • backend route handlers;
  • scheduled jobs;
  • internal integration services;
  • local development tools.

Do not place API keys in:

  • browser bundles or static sites;
  • mobile apps distributed to end users;
  • screenshots, tickets, or shared chat messages;
  • logs, analytics events, or client-side error reporting;
  • public repositories or checked-in config files.

If you need browser-based behavior, send the request through your own backend and inject the Siesta AI credentials there.

Key Storage And Rotation​

Store the API key in a secret manager or environment variable controlled by your backend deployment. Keep X-Org-Id alongside the integration configuration so each environment points to the correct organization.

Recommended setup:

  1. Keep production and non-production keys separate.
  2. Use one integration identity per environment or app surface when possible.
  3. Rotate keys by updating the backend secret first, then re-testing a read-only endpoint.
  4. Remove unused keys when an integration is retired.

Testing From The Docs​

The API reference includes an inline Try request section for quick testing. Values entered there are kept in the browser session and are not committed to the docs repository or placed in the page URL.

Use that mode only for controlled local validation. If browser policy, company network rules, or CORS settings prevent the request from being sent from the docs domain, use the generated curl command instead.

Common Status Codes​

  • 400 Bad Request: invalid input, unsupported parameter combination, or malformed payload.
  • 401 Unauthorized: missing, expired, or invalid API key.
  • 403 Forbidden: the key is valid but does not have access to the resource or organization.
  • 404 Not Found: the resource does not exist or is not visible to the current organization.
  • 429 Too Many Requests: the client is sending requests too quickly.
  • 500 Internal Server Error: unexpected server-side failure. Show a fallback message and keep enough local context to retry safely.

Review the response section for each endpoint in the REST API Reference for exact documented response shapes.

  1. Read the endpoint in the reference.
  2. Copy the curl sample and replace placeholders.
  3. Test with a read-only request.
  4. Generate typed helpers from the OpenAPI document if your integration is large.

Security And Governance​

Apply the same governance to API integrations as to in-product use:

  • Restrict each integration to the minimum workflow it needs.
  • Prefer separate agents for different integration contexts.
  • Use connection governance for tools that read sensitive data or modify external systems.
  • Require 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.
Last updated on