Integrate via REST API

Your AI employees are accessible via a REST API. Any system that can make HTTP requests can send prompts and receive responses. No SDK needed, just curl or your favorite HTTP client.

TL;DR

Generate an API key in Settings, Communications. Send a POST to /api/v1/chat with the employee ID and your prompt. Get the response back as JSON. The API uses the same execution pipeline as web chat, so the employee has full access to its skills, tools, and memory.

When to Use This

• Your backend service sends tasks to employees on a schedule (cron jobs, batch processing)
• Your Slack bot forwards user messages to an employee and posts the response back
• Your internal admin tool triggers employee actions from a dashboard button
• Your CI/CD pipeline asks an employee to review code or generate release notes
• Your mobile app integrates employee responses into a custom UI

How It Works

The API exposes a single endpoint for chatting with employees. Requests are synchronous: the API blocks until the employee responds (up to 5 minutes). Messages go through the same execution pipeline as web chat: same skills, same memory, same tools, same billing.

• One endpoint. POST /api/v1/chat sends a message and returns the response
• Same execution. API messages run through the Dispatcher and execution pipeline, identical to every other channel
• Same billing. Credits are tracked and charged the same way
• Shared keys. API keys work across all programmatic channels (REST API, MCP Server, A2A, Webhooks, and Email)

Authentication

All requests require a Bearer token in the Authorization header.

1. Go to Settings, Communications
2. Expand the Programmatic group
3. Expand any channel card (API Access, MCP Server, etc.)
4. Click "New Key", give it a name, hit Enter
5. Copy the key from the green banner. It will not be shown again

Include it in every request:

Authorization: Bearer sk-your-api-key-here

Keys are shared across all programmatic channels. One key works for the REST API, MCP Server, A2A, Webhooks, and Email.

Enable the Channel

The API channel is disabled by default. Enable it before making requests:

1. Go to Settings, Technical, Communications
2. Find API under the Inbound channels
3. Toggle it on

Without this, requests will return a 403 error.

Endpoints

POST /api/v1/chat

Send a prompt to an AI employee and receive their response.

Finding employee IDs. Employee UUIDs are visible in the browser URL when viewing an employee's profile (e.g., /employees/abc-123-...).

Request body:

Response (200 OK):

GET /api/v1/health

Returns {"status": "ok"} if the service is running. Requires authentication.

Error Responses

Rate Limits

• Per-IP (failed auth): 10 attempts per minute. Prevents key brute-forcing
• Per-API-key: 120 requests per minute. Prevents abuse

Exceeding limits returns 429 Too Many Requests with a Retry-After: 60 header.

Quick Start

curl

curl -X POST https://api-sistava.com/api/v1/chat \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "YOUR_EMPLOYEE_UUID",
    "prompt": "What can you help me with?"
  }'

Python

import requests

response = requests.post(
    "https://api-sistava.com/api/v1/chat",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "employee_id": "YOUR_EMPLOYEE_UUID",
        "prompt": "Draft a follow-up email for the client meeting."
    },
)
data = response.json()
print(data["content"])

JavaScript / Node

const response = await fetch("https://api-sistava.com/api/v1/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    employee_id: "YOUR_EMPLOYEE_UUID",
    prompt: "What tasks are pending this week?",
  }),
});
const { content } = await response.json();
console.log(content);

API vs MCP Server vs A2A

Good to Know

• Synchronous. The API blocks until the employee responds (up to 5 minutes). For fire-and-forget, use the Webhook channel instead
• Team leaders. If the employee is a team leader, they may delegate to team members. Same behavior as web chat
• Body size limit. Request body cannot exceed 64 KB. For large documents, use file upload through the web app instead
• Finding employee IDs. Employee UUIDs are visible in the browser URL when viewing an employee's profile
• Managing keys. Create, rename, and revoke keys from the Communications page. Revoking a key immediately blocks all requests using it across every channel

Frequently Asked Questions

Q: Do I need a separate API key for each channel? A: No. API keys are shared across all programmatic channels. One key works for the REST API, MCP Server, A2A, Webhooks, and Email.

Q: Can I send messages to a team instead of an individual employee? A: Send to a team leader's employee ID. The leader will delegate to team members as needed, the same way it works in web chat.

Q: What happens if the employee takes longer than 5 minutes? A: You get a 504 timeout. Break the task into smaller prompts, or use the Webhook channel for fire-and-forget tasks.

Q: Is there a streaming version of the API? A: Use the A2A channel with tasks/sendSubscribe for streaming responses via Server-Sent Events. The REST API is synchronous only.

Q: How do I find my employee's UUID? A: Open the employee's profile in the web app. The UUID is in the browser URL (e.g., /employees/abc-123-...).