API Documentation
Complete reference for the LiquidCortex REST API. Build powerful integrations with your AI workforce.
Getting Started
The LiquidCortex API enables you to programmatically interact with your AI employees. Send messages, create tasks, manage workflows, and more.
Base URL
https://api.liquidcortex.com/v1Quick Start
1Get your API Key
Navigate to Developer Hub and create a new API key. Keep it secure - it grants full access to your account.
2Make your first request
curl https://api.liquidcortex.com/v1/employees \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"3Chat with an employee
curl -X POST https://api.liquidcortex.com/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_id": "atlas",
"message": "Schedule a team standup for tomorrow at 10am"
}'Authentication
All API requests require authentication using Bearer tokens. Include your API key in the Authorization header of every request.
Request Header
Authorization: Bearer lc_live_sk_xxxxxxxxxxxxxxxxxxxxAPI Key Types
Prefix: lc_live_sk_
Use in production. Consumes credits.
Prefix: lc_test_sk_
Use for development. Free but rate-limited.
Security Warning: Never expose API keys in client-side code, public repositories, or logs. Rotate keys immediately if compromised.
Employees
Manage and interact with your AI employees. Each employee has specialized skills and capabilities.
/employeesList all available AI employees in your organization.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by category (sales, engineering, etc.) |
status | string | No | Filter by status (active, idle, offline) |
limit | integer | No | Max results (default: 50, max: 100) |
Response
{
"employees": [
{
"id": "atlas",
"name": "Atlas",
"role": "Executive Assistant",
"category": "operations",
"status": "active",
"capabilities": ["scheduling", "email", "task_management"],
"tier": "starter"
},
{
"id": "sterling",
"name": "Sterling",
"role": "Sales Strategist",
"category": "sales",
"status": "active",
"capabilities": ["crm", "outreach", "forecasting"],
"tier": "manager"
}
],
"total": 44,
"has_more": false
}/employees/:idGet detailed information about a specific employee.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The employee ID (e.g., "atlas", "sterling") |
Response
{
"id": "atlas",
"name": "Atlas",
"role": "Executive Assistant",
"category": "operations",
"description": "Your AI chief of staff for scheduling, email management, and task coordination.",
"capabilities": ["scheduling", "email", "task_management", "meeting_prep"],
"status": "active",
"stats": {
"tasks_completed_today": 47,
"avg_response_time_ms": 1200,
"satisfaction_score": 4.9
},
"tier": "starter",
"created_at": "2024-01-15T00:00:00Z"
}/employees/:id/statsGet usage statistics for a specific employee.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
period | string | No | Time period: 24h, 7d, 30d, 90d (default: 7d) |
Chat & Conversations
Send messages to AI employees and manage conversation history. Supports both synchronous and streaming responses.
/chatSend a message to an AI employee and receive a response.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
employee_id | string | Yes | ID of the employee to chat with |
message | string | Yes | The message to send |
conversation_id | string | No | Continue existing conversation |
stream | boolean | No | Enable streaming response (default: false) |
context | object | No | Additional context for the employee |
Example Request
{
"employee_id": "atlas",
"message": "Schedule a meeting with the marketing team for tomorrow at 2pm",
"context": {
"user_timezone": "America/New_York",
"calendar_access": true
}
}Response
{
"id": "msg_abc123xyz",
"conversation_id": "conv_def456",
"employee_id": "atlas",
"content": "I've scheduled a meeting with the marketing team for tomorrow (January 2nd) at 2:00 PM EST. I've sent calendar invites to all team members. Is there anything specific you'd like me to add to the agenda?",
"role": "assistant",
"credits_used": 1,
"created_at": "2026-01-01T15:30:00Z"
}/chat/streamSend a message with Server-Sent Events (SSE) streaming response.
Streaming: Response is sent as SSE events. Each event contains a chunk of the response.
curl -X POST https://api.liquidcortex.com/v1/chat/stream \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"employee_id": "atlas", "message": "Draft an email..."}'/conversationsList all conversations for the authenticated user.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
employee_id | string | No | Filter by employee |
limit | integer | No | Max results (default: 20) |
before | string | No | Cursor for pagination |
/conversations/:idGet a specific conversation with full message history.
/conversations/:idDelete a conversation and all its messages.
Tasks
Create, manage, and track tasks assigned to AI employees. Tasks can be one-time or recurring.
/tasksCreate a new task for an AI employee.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
employee_id | string | Yes | Employee to assign the task to |
title | string | Yes | Task title |
description | string | No | Detailed task description |
due_at | string | No | ISO 8601 due date |
priority | string | No | low, medium, high, urgent |
recurring | object | No | Recurrence settings |
Example Request
{
"employee_id": "atlas",
"title": "Send weekly team summary",
"description": "Compile and send a summary of team activities to stakeholders",
"priority": "medium",
"recurring": {
"frequency": "weekly",
"day": "friday",
"time": "17:00"
}
}/tasksList all tasks with optional filters.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
employee_id | string | No | Filter by assigned employee |
status | string | No | pending, in_progress, completed, failed |
priority | string | No | Filter by priority level |
/tasks/:idGet details of a specific task.
/tasks/:idUpdate a task's status, priority, or other properties.
/tasks/:idDelete a task.
Knowledge Base
Upload documents and data that your AI employees can reference. Supports PDF, DOCX, TXT, and more.
/knowledge/documentsUpload a document to the knowledge base.
Content-Type: Use multipart/form-data for file uploads.
Form Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
file | file | Yes | The document file (max 50MB) |
name | string | No | Display name for the document |
tags | string[] | No | Tags for organization |
employee_ids | string[] | No | Restrict access to specific employees |
/knowledge/documentsList all documents in the knowledge base.
/knowledge/documents/:idDelete a document from the knowledge base.
/knowledge/querySearch the knowledge base with semantic search.
Request Body
{
"query": "What is our refund policy?",
"limit": 5,
"filters": {
"tags": ["policies", "customer-support"]
}
}Workflows
Create automated workflows that chain multiple AI employees together for complex tasks.
/workflowsCreate a new workflow.
Example: Lead Qualification Workflow
{
"name": "Lead Qualification Pipeline",
"trigger": {
"type": "webhook",
"event": "new_lead"
},
"steps": [
{
"employee_id": "hunter",
"action": "qualify_lead",
"input": "{{trigger.data}}"
},
{
"employee_id": "sterling",
"action": "create_proposal",
"condition": "{{steps[0].score > 70}}",
"input": "{{steps[0].output}}"
},
{
"employee_id": "atlas",
"action": "schedule_meeting",
"input": "{{steps[1].output}}"
}
]
}/workflowsList all workflows.
/workflows/:id/runManually trigger a workflow execution.
/workflows/:id/runsGet execution history for a workflow.
Integrations
Connect third-party services to extend employee capabilities.
/integrationsList all available and connected integrations.
/integrations/:provider/connectInitiate OAuth connection for an integration.
Supported Providers
/integrations/:providerDisconnect an integration.
Webhooks
Receive real-time notifications when events occur in your LiquidCortex account.
/webhooksCreate a new webhook endpoint.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The HTTPS URL to receive webhook events |
events | string[] | Yes | Events to subscribe to |
secret | string | No | Secret for signing payloads |
Available Events
chat.message.createdtask.completedtask.failedworkflow.completedemployee.status.changedcredits.low/webhooksList all webhook endpoints.
/webhooks/:idDelete a webhook endpoint.
Webhook Payload Signature
All webhook payloads are signed with HMAC-SHA256. Verify the signature using theX-LiquidCortex-Signature header.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}Rate Limits
API requests are rate-limited based on your subscription tier. Limits reset every minute.
| Tier | Requests/min | Burst | Concurrent |
|---|---|---|---|
| Starter | 60 | 10 | 5 |
| Manager | 300 | 50 | 20 |
| Agency | 1,000 | 200 | 100 |
Rate Limit Headers
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1704067260Error Handling
The API uses standard HTTP status codes and returns detailed error messages in JSON format.
Error Response Format
{
"error": {
"code": "invalid_request",
"message": "The 'employee_id' field is required",
"param": "employee_id",
"doc_url": "https://docs.liquidcortex.com/errors/invalid_request"
}
}HTTP Status Codes
Common Error Codes
invalid_api_keyAPI key is invalid or expired
insufficient_creditsNot enough credits for this operation
employee_not_foundThe specified employee does not exist
rate_limit_exceededToo many requests, try again later
SDKs & Libraries
Official and community SDKs to integrate LiquidCortex into your applications.
pip install liquidcortexnpm install @liquidcortex/sdkgo get github.com/liquidcortex/go-sdkgem install liquidcortexNeed Help?
Our developer support team is here to help you build amazing integrations.