Developers/Documentation

API Documentation

Complete reference for the LiquidCortex REST API. Build powerful integrations with your AI workforce.

API Version: v1Last updated: January 2026

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/v1

Quick 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_xxxxxxxxxxxxxxxxxxxx

API Key Types

Live Keys

Prefix: lc_live_sk_
Use in production. Consumes credits.

Test Keys

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.

GET/employees

List all available AI employees in your organization.

Query Parameters

ParameterTypeRequiredDescription
categorystringNoFilter by category (sales, engineering, etc.)
statusstringNoFilter by status (active, idle, offline)
limitintegerNoMax 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
}
GET/employees/:id

Get detailed information about a specific employee.

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe 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"
}
GET/employees/:id/stats

Get usage statistics for a specific employee.

Query Parameters

ParameterTypeRequiredDescription
periodstringNoTime period: 24h, 7d, 30d, 90d (default: 7d)

Chat & Conversations

Send messages to AI employees and manage conversation history. Supports both synchronous and streaming responses.

POST/chat

Send a message to an AI employee and receive a response.

Request Body

ParameterTypeRequiredDescription
employee_idstringYesID of the employee to chat with
messagestringYesThe message to send
conversation_idstringNoContinue existing conversation
streambooleanNoEnable streaming response (default: false)
contextobjectNoAdditional 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"
}
POST/chat/stream

Send 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..."}'
GET/conversations

List all conversations for the authenticated user.

Query Parameters

ParameterTypeRequiredDescription
employee_idstringNoFilter by employee
limitintegerNoMax results (default: 20)
beforestringNoCursor for pagination
GET/conversations/:id

Get a specific conversation with full message history.

DELETE/conversations/:id

Delete a conversation and all its messages.

Tasks

Create, manage, and track tasks assigned to AI employees. Tasks can be one-time or recurring.

POST/tasks

Create a new task for an AI employee.

Request Body

ParameterTypeRequiredDescription
employee_idstringYesEmployee to assign the task to
titlestringYesTask title
descriptionstringNoDetailed task description
due_atstringNoISO 8601 due date
prioritystringNolow, medium, high, urgent
recurringobjectNoRecurrence 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"
  }
}
GET/tasks

List all tasks with optional filters.

Query Parameters

ParameterTypeRequiredDescription
employee_idstringNoFilter by assigned employee
statusstringNopending, in_progress, completed, failed
prioritystringNoFilter by priority level
GET/tasks/:id

Get details of a specific task.

PATCH/tasks/:id

Update a task's status, priority, or other properties.

DELETE/tasks/:id

Delete a task.

Knowledge Base

Upload documents and data that your AI employees can reference. Supports PDF, DOCX, TXT, and more.

POST/knowledge/documents

Upload a document to the knowledge base.

Content-Type: Use multipart/form-data for file uploads.

Form Fields

ParameterTypeRequiredDescription
filefileYesThe document file (max 50MB)
namestringNoDisplay name for the document
tagsstring[]NoTags for organization
employee_idsstring[]NoRestrict access to specific employees
GET/knowledge/documents

List all documents in the knowledge base.

DELETE/knowledge/documents/:id

Delete a document from the knowledge base.

POST/knowledge/query

Search 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.

POST/workflows

Create 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}}"
    }
  ]
}
GET/workflows

List all workflows.

POST/workflows/:id/run

Manually trigger a workflow execution.

GET/workflows/:id/runs

Get execution history for a workflow.

Integrations

Connect third-party services to extend employee capabilities.

GET/integrations

List all available and connected integrations.

POST/integrations/:provider/connect

Initiate OAuth connection for an integration.

Supported Providers

slackgoogle-calendaroutlookgithubsalesforce
DELETE/integrations/:provider

Disconnect an integration.

Webhooks

Receive real-time notifications when events occur in your LiquidCortex account.

POST/webhooks

Create a new webhook endpoint.

Request Body

ParameterTypeRequiredDescription
urlstringYesThe HTTPS URL to receive webhook events
eventsstring[]YesEvents to subscribe to
secretstringNoSecret for signing payloads

Available Events

chat.message.created
task.completed
task.failed
workflow.completed
employee.status.changed
credits.low
GET/webhooks

List all webhook endpoints.

DELETE/webhooks/:id

Delete 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.

TierRequests/minBurstConcurrent
Starter60105
Manager3005020
Agency1,000200100

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1704067260

Error 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

200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Server Error - Something went wrong on our end

Common Error Codes

invalid_api_key

API key is invalid or expired

insufficient_credits

Not enough credits for this operation

employee_not_found

The specified employee does not exist

rate_limit_exceeded

Too many requests, try again later

SDKs & Libraries

Official and community SDKs to integrate LiquidCortex into your applications.

🐍Python
official
pip install liquidcortex
💚Node.js
official
npm install @liquidcortex/sdk
🔵Go
community
go get github.com/liquidcortex/go-sdk
💎Ruby
community
gem install liquidcortex

Need Help?

Our developer support team is here to help you build amazing integrations.