API Reference

The Aurex API lets you integrate AI agents into any application, website, or workflow. All endpoints return JSON. Authentication uses API keys passed via the x-api-key header.

Base URL

https://yourdomain.com

Quick Start

# 1. Get your API key from Dashboard → API Keys

# 2. Start a conversation
curl -X POST https://yourdomain.com/api/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentId": "YOUR_AGENT_ID",
    "contact": "John Doe",
    "message": "Hi, I need help booking an appointment"
  }'

# 3. Response
{
  "conversation": { "id": "clx...", "status": "OPEN" },
  "aiMessage": { "role": "assistant", "content": "Hello John! I'd be happy to help you book an appointment..." }
}

Aurex uses API keys for programmatic access. Include your key in the x-api-key header on every request.

POST/api/register

Create a new user account.

Request Body

namestring — Full name
emailstring — Email address
passwordstring — Min 6 characters

Response

{ "id": "clx...", "email": "[email protected]", "name": "Jane Smith" }

Create and manage AI agents. Each agent has a type and an optional custom system prompt.

GET/api/agents🔑 Auth required

List all agents for the authenticated user.

Response

[
  {
    "id": "clx...",
    "name": "Hotel Support Bot",
    "type": "CUSTOMER_SUPPORT",
    "systemPrompt": "You are a hotel concierge...",
    "isActive": true,
    "_count": { "conversations": 42 }
  }
]
POST/api/agents🔑 Auth required

Create a new agent. Plan limits apply.

Request Body

namestring — Agent display name
typeCUSTOMER_SUPPORT | LEAD_FOLLOWUP | APPOINTMENT_BOOKING | REPORT_GENERATOR
systemPromptstring? — Custom instructions (optional)

Response

{
  "id": "clx...",
  "name": "Hotel Support Bot",
  "type": "CUSTOMER_SUPPORT",
  "isActive": true,
  "createdAt": "2025-01-01T00:00:00.000Z"
}
PATCH/api/agents/:id🔑 Auth required

Update an agent's name, prompt, or active status.

Request Body

namestring? — New name
systemPromptstring? — New prompt
isActiveboolean? — Enable or pause

Response

{ "id": "clx...", "name": "Updated Name", "isActive": false }
DELETE/api/agents/:id🔑 Auth required

Delete an agent and all its conversations.

Response

{ "success": true }

Start and continue AI-powered conversations. Each message triggers a GPT-4o response.

GET/api/conversations🔑 Auth required

List conversations. Filter by agent using ?agentId=

Response

[
  {
    "id": "clx...",
    "contact": "John Doe",
    "status": "OPEN",
    "agent": { "id": "clx...", "name": "Support Bot" },
    "messages": [
      { "role": "user", "content": "Hi, I need help" },
      { "role": "assistant", "content": "Hello! How can I help?" }
    ]
  }
]
POST/api/conversations🔑 Auth required

Start a new conversation. Returns the AI's first reply.

Request Body

agentIdstring — ID of the agent to use
contactstring — Customer name or identifier
messagestring — First message from the customer

Response

{
  "conversation": { "id": "clx...", "contact": "John", "status": "OPEN" },
  "aiMessage": { "role": "assistant", "content": "Hello John! How can I help?" }
}

Example

curl -X POST https://yourdomain.com/api/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"agentId":"clx...","contact":"John","message":"Hi, I need help"}'
POST/api/conversations/:id🔑 Auth required

Send a message to an existing conversation.

Request Body

messagestring — Message content

Response

{ "id": "clx...", "role": "assistant", "content": "Here is my reply..." }
PATCH/api/conversations/:id🔑 Auth required

Update conversation status.

Request Body

statusOPEN | RESOLVED | ESCALATED

Response

{ "count": 1 }

Embed a chat widget on any website with a single script tag.

GET/api/widget?agentId=:id

Returns the embeddable JavaScript widget for a given agent.

Response

// JavaScript widget bundle

Example

<!-- Add before </body> on your website -->
<script
  src="https://yourdomain.com/api/widget?agentId=YOUR_AGENT_ID"
  async
></script>

Receive real-time event notifications when conversations are created, updated, or resolved.

GET/api/webhooks🔑 Auth required

List all configured webhook endpoints.

Response

[
  {
    "id": "clx...",
    "url": "https://your-system.com/webhook",
    "events": ["conversation.created", "message.created"],
    "secret": "whsec_..."
  }
]
POST/api/webhooks🔑 Auth required

Register a new webhook endpoint.

Request Body

urlstring — Your endpoint URL
eventsstring[] — Events to subscribe to

Response

{ "id": "clx...", "url": "...", "secret": "whsec_..." }

Example

// Webhook payload example
{
  "event": "conversation.created",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "data": {
    "id": "clx...",
    "contact": "John Doe",
    "agentId": "clx...",
    "status": "OPEN"
  }
}
DELETE/api/webhooks/:id🔑 Auth required

Remove a webhook endpoint.

Response

{ "success": true }

Connect Aurex to external platforms using these webhook endpoints.

POST/api/integrations/zapier

Trigger an agent from a Zapier workflow.

Request Body

agentIdstring — Agent to use
contactstring — Contact identifier
messagestring — Message to process

Response

{ "reply": "AI response text" }

Example

// Required header
x-api-key: YOUR_API_KEY
POST/api/integrations/whatsapp

Twilio WhatsApp webhook. Set this as your Twilio webhook URL.

Response

// TwiML response with AI reply

Example

// Set in Twilio Console:
// Webhook URL: https://yourdomain.com/api/integrations/whatsapp
// Required .env:
TWILIO_AUTH_TOKEN=your_token
WHATSAPP_DEFAULT_AGENT_ID=clx...
POST/api/integrations/messenger

Facebook Messenger webhook for auto-replies.

Response

{ "status": "ok" }

Example

// Required .env:
MESSENGER_VERIFY_TOKEN=your_token
MESSENGER_PAGE_ACCESS_TOKEN=your_token
MESSENGER_DEFAULT_AGENT_ID=clx...
POST/api/integrations/slack

Slack slash command handler. Use /Aurex in your workspace.

Request Body

textstring — agentId + message

Response

{ "text": "AI reply" }

Webhook Events

Subscribe to these events when registering a webhook endpoint. Aurex signs each payload with your webhook secret using HMAC-SHA256.

conversation.createdA new conversation was started
conversation.updatedConversation status changed
conversation.resolvedConversation marked as resolved
conversation.escalatedConversation escalated to human
message.createdA new message was sent or received

Verifying Webhook Signatures

// Node.js example
import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Error Codes

All errors return a JSON object with an error field describing the issue.

400Bad RequestInvalid or missing request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenPlan limit reached or insufficient permissions
404Not FoundResource does not exist or belongs to another user
409ConflictResource already exists (e.g. duplicate email)
429Too Many RequestsRate limit exceeded — retry after 60 seconds
500Server ErrorUnexpected server error — contact support

Error Response Format

{
  "error": "Upgrade your plan to create more agents"
}

Rate Limits

Free plan60 requests / minute
Starter plan300 requests / minute
Pro plan1,000 requests / minute
Agency planUnlimited

Need help? [email protected]

© 2025 Aurex. All rights reserved.