API Reference

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

const headers = {
  Authorization: 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json',
}

Agents API

Create Agent

Create a new AI agent.

Endpoint: POST /api/agents

Request Body:

{
  name: string
  description: string
  model: 'gpt-4' | 'gpt-3.5-turbo' | 'claude-3'
  systemPrompt?: string
  temperature?: number
  maxTokens?: number
}

Response:

{
  id: string
  name: string
  description: string
  model: string
  createdAt: string
  status: 'active' | 'inactive'
}

Get Agent

Retrieve an agent by ID.

Endpoint: GET /api/agents/:id

Response:

{
  id: string
  name: string
  description: string
  model: string
  configuration: object
  createdAt: string
  updatedAt: string
}

List Agents

List all agents in your workspace.

Endpoint: GET /api/agents

Query Parameters:

• page (number): Page number for pagination
• limit (number): Number of results per page
• status (string): Filter by status

Response:

{
  agents: Agent[]
  total: number
  page: number
  limit: number
}

Update Agent

Update an existing agent.

Endpoint: PATCH /api/agents/:id

Request Body:

{
  name?: string
  description?: string
  model?: string
  configuration?: object
}

Delete Agent

Delete an agent.

Endpoint: DELETE /api/agents/:id

Response:

{
  success: boolean
  message: string
}

Conversations API

Create Conversation

Start a new conversation with an agent.

Endpoint: POST /api/conversations

Request Body:

{
  agentId: string
  userId?: string
  metadata?: object
}

Response:

{
  id: string
  agentId: string
  userId: string
  createdAt: string
  status: 'active' | 'completed'
}

Send Message

Send a message in a conversation.

Endpoint: POST /api/conversations/:id/messages

Request Body:

{
  content: string
  role: 'user' | 'assistant' | 'system'
  metadata?: object
}

Response:

{
  id: string
  conversationId: string
  content: string
  role: string
  createdAt: string
}

Get Conversation History

Retrieve the message history for a conversation.

Endpoint: GET /api/conversations/:id/messages

Query Parameters:

• limit (number): Number of messages to retrieve
• before (string): Cursor for pagination

Response:

{
  messages: Message[]
  hasMore: boolean
  nextCursor?: string
}

Webhooks

Register Webhook

Register a webhook to receive events.

Endpoint: POST /api/webhooks

Request Body:

{
  url: string
  events: string[]
  secret?: string
}

Available Events:

• agent.created
• agent.updated
• agent.deleted
• conversation.started
• conversation.completed
• message.sent
• message.received

Rate Limits

API requests are rate-limited based on your plan:

• Free: 100 requests/hour
• Pro: 1,000 requests/hour
• Enterprise: Custom limits

Error Handling

All errors follow a consistent format:

{
  error: {
    code: string
    message: string
    details?: object
  }
}

Common Error Codes:

• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Rate Limit Exceeded
• 500: Internal Server Error