Lumnis AI
Docs
API Reference

API Reference

Complete API documentation for the Lumnis AI REST API

Overview

The Lumnis AI API (api.lumnis.ai) provides developers with access to advanced AI agent capabilities through a simple REST API. This documentation covers all endpoints, authentication, request/response formats, and best practices for integrating with Lumnis AI.

Base URL

https://api.lumnis.ai

Authentication

All API requests require authentication using an API key provided in the request headers.

API Key Header

X-API-Key: your-api-key-here

Example Request

curl -X GET https://api.lumnis.ai/v1/threads \
  -H "X-API-Key: your-api-key-here"

API Endpoints

Health Check

GET /health

Check if the API is operational. No authentication required.

Response

{
  "status": "ok"
}

GET /health/detailed

Get detailed health information including database connections and circuit breaker states.

Response

{
  "status": "ok",
  "timestamp": "2024-01-20T10:30:00Z",
  "db\_pool": {
    "size": 10,
    "checked\_in": 8,
    "overflow": 0
  },
  "circuit\_breakers": {
    "openai": "closed",
    "anthropic": "closed"
  }
}

Responses API

The Responses API allows you to create AI-powered responses asynchronously.

POST /v1/responses

Create a new AI response. Responses are processed asynchronously.

Request Body

{
  "thread\_id": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    {
      "role": "user",
      "content": "What are the latest trends in AI?"
    }
  ],
  "agent\_effort": "medium",
  "cost\_cap\_usd": 5.00,
  "user\_id": "user@example.com",
  "priority": 5,
  "agent\_config": {
    "plan\_strategy": "hypertree",
    "planner\_model\_type": "SMART_MODEL",
    "coordinator\_model\_type": "SMART_MODEL"
  }
}

Field descriptions:

  • thread_id (optional): Existing thread ID to continue conversation
  • agent_effort: Processing effort level - low, medium, or high
  • cost_cap_usd (optional): Maximum cost in USD (max 10000)
  • user_id (optional): User identifier for tracking
  • priority: Request priority from 1-10 (default 5)
  • agent_config (optional): Advanced agent configuration

Headers

  • Idempotency-Key (optional): Ensure exactly-once processing

Response (202 Accepted)

{
  "response\_id": "resp_123456789",
  "thread\_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created\_at": "2024-01-20T10:30:00Z"
}

GET /v1/responses/{responseId}

Get the status and content of a response.

Query Parameters

  • wait (optional): Wait up to N seconds (1-30) for response completion

Response

{
  "response\_id": "resp_123456789",
  "thread\_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "messages": [
    {
      "role": "assistant",
      "content": "Here are the latest AI trends..."
    }
  ],
  "usage": {
    "total\_tokens": 1234,
    "prompt\_tokens": 234,
    "completion\_tokens": 1000,
    "cost\_usd": 0.05
  },
  "created\_at": "2024-01-20T10:30:00Z",
  "completed\_at": "2024-01-20T10:31:00Z"
}

Status values: processing, completed, failed, cancelled

POST /v1/responses/{responseId}/cancel

Cancel a processing response.

Response

{
  "response\_id": "resp_123456789",
  "status": "cancelled",
  "message": "Response cancelled successfully"
}

GET /v1/responses/{responseId}/artifacts

List artifacts (files, data) generated by the response.

Query Parameters

  • limit: 1-100 (default 20)
  • offset: Pagination offset

Response

{
  "artifacts": [
    {
      "artifact\_id": "art_123",
      "name": "analysis_report.pdf",
      "type": "file",
      "size\_bytes": 102400,
      "created\_at": "2024-01-20T10:31:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Threads API

Manage conversation threads for organizing related responses.

GET /v1/threads

List all threads.

Query Parameters

  • user_id (optional): Filter by user
  • limit: 1-100 (default 20)
  • offset: Pagination offset

Response

{
  "threads": [
    {
      "thread\_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "AI Trends Discussion",
      "created\_at": "2024-01-20T10:00:00Z",
      "updated\_at": "2024-01-20T10:31:00Z",
      "message\_count": 5,
      "user\_id": "user@example.com"
    }
  ],
  "total": 25,
  "limit": 20,
  "offset": 0
}

GET /v1/threads/{threadId}/responses

Get all responses in a thread.

Query Parameters

  • limit: 1-100 (default 20)
  • offset: Pagination offset

Response

[
  {
    "response\_id": "resp_123456789",
    "status": "completed",
    "messages": [...],
    "created\_at": "2024-01-20T10:30:00Z"
  }
]

PATCH /v1/threads/{threadId}

Update thread metadata.

Request Body

{
  "title": "Updated Thread Title"
}

Users API

Manage users within your tenant.

POST /v1/users

Create a new user.

Request Body

{
  "email": "user@example.com",
  "first\_name": "John",
  "last\_name": "Doe"
}

Response

{
  "user\_id": "usr_123456789",
  "email": "user@example.com",
  "first\_name": "John",
  "last\_name": "Doe",
  "created\_at": "2024-01-20T10:00:00Z"
}

GET /v1/users

List all users with pagination.

Query Parameters

  • page: Page number (≥1)
  • page_size: 1-100 (default 20)

Response

{
  "users": [...],
  "total": 50,
  "page": 1,
  "page\_size": 20
}

GET /v1/users/{userIdentifier}

Get user by ID or email.

PUT /v1/users/{userIdentifier}

Update user information.

DELETE /v1/users/{userIdentifier}

Deactivate a user.

GET /v1/users/{userIdentifier}/responses

Get all responses created by a user.

GET /v1/users/{userIdentifier}/threads

Get all threads associated with a user.

External API Keys

Manage external API keys for AI providers (OpenAI, Anthropic, etc.).

POST /v1/external-api-keys

Store an external API key.

Request Body

{
  "provider": "OPENAI_API_KEY",
  "api\_key": "sk-..."
}

Supported Providers

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GOOGLE_API_KEY
  • EXA_API_KEY
  • SERPAPI_API_KEY

Response

{
  "key\_id": "key_123456789",
  "provider": "OPENAI_API_KEY",
  "created\_at": "2024-01-20T10:00:00Z",
  "last\_used\_at": null
}

GET /v1/external-api-keys

List all stored external API keys.

DELETE /v1/external-api-keys/{provider}

Delete an external API key.

GET /v1/external-api-keys/mode

Get current API key mode.

Response

{
  "mode": "byo_keys"  // or "platform"
}

PATCH /v1/external-api-keys/mode

Update API key mode.

Request Body

{
  "mode": "byo_keys"
}

Composio Integration

Connect external services and tools via Composio.

POST /v1/composio/connections/initiate

Initiate OAuth connection to external service.

Request Body

{
  "user\_id": "user@example.com",
  "app\_name": "GITHUB",
  "redirect\_url": "https://yourapp.com/callback"
}

Supported Apps

  • GITHUB
  • SLACK
  • NOTION
  • LINEAR
  • JIRA
  • And more...

Response

{
  "redirect\_url": "https://github.com/login/oauth/authorize?...",
  "connection\_id": "conn_123456789"
}

GET /v1/composio/connections/{userId}/{appName}

Check connection status.

Response

{
  "status": "connected",
  "connected\_at": "2024-01-20T10:00:00Z",
  "connection\_id": "conn_123456789"
}

GET /v1/composio/connections/{userId}

Get all user connections.

Query Parameters

  • app_filter: Comma-separated app names

POST /v1/composio/tools

Get available tools for connected apps.

Request Body

{
  "user\_id": "user@example.com",
  "apps": ["GITHUB", "SLACK"],
  "tags": ["repository", "messaging"]
}

POST /v1/composio/connections/disconnect

Disconnect an app.

Request Body

{
  "user\_id": "user@example.com",
  "app\_name": "GITHUB"
}

Error Handling

All API errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "messages",
      "reason": "Messages array cannot be empty"
    },
    "type": "ValidationError",
    "request\_id": "req_123456789",
    "trace\_id": "trace_123456789"
  }
}

Common Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request parameters
AUTHENTICATION_ERROR401Missing or invalid API key
AUTHORIZATION_ERROR403Access denied to resource
NOT_FOUND404Resource not found
RATE_LIMIT_ERROR429Too many requests
INTERNAL_ERROR500Internal server error
TENANT_NOT_AVAILABLE503Tenant service temporarily unavailable

Rate Limiting

API requests are subject to rate limiting to ensure fair usage:

  • Default limit: 100 requests per minute per API key
  • Response headers:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Requests remaining
    • X-RateLimit-Reset: Unix timestamp when limit resets

Best Practices

1. Use Idempotency Keys

For critical operations like response creation, use idempotency keys:

curl -X POST https://api.lumnis.ai/v1/responses \
  -H "X-API-Key: your-api-key" \
  -H "Idempotency-Key: unique-request-id" \
  -d '{...}'

2. Implement Exponential Backoff

When encountering rate limits or errors, implement exponential backoff:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;
      if (response.status !== 429 && response.status < 500) throw new Error();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
    await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
  }
}

3. Use Long Polling for Real-time Updates

For real-time response updates, use the wait parameter:

const response = await fetch(
  'https://api.lumnis.ai/v1/responses/resp_123?wait=30',
  { headers: { 'X-API-Key': 'your-api-key' } }
);

4. Handle Async Processing

Responses are processed asynchronously. Poll for status:

async function waitForResponse(responseId, apiKey) {
  while (true) {
    const response = await fetch(
      `https://api.lumnis.ai/v1/responses/${responseId}?wait=10`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const data = await response.json();
    
    if (data.status === 'completed' || data.status === 'failed') {
      return data;
    }
  }
}

5. Organize with Threads

Use threads to organize related conversations:

// Create a thread for a specific topic
const thread = await createThread({ title: "Product Research" });
const response1 = await createResponse({
  thread_id: thread.thread_id,
  messages: [{ role: "user", content: "Research competitors" }]
});

SDK Examples

Python

from lumnis import LumnisClient
 
client = LumnisClient(api_key="your-api-key")
 
# Create a response
response = client.responses.create(
    messages=[
        {"role": "user", "content": "Analyze this data..."}
    ],
    agent_effort="high",
    cost_cap_usd=10.00
)
 
# Wait for completion
result = client.responses.wait_for_completion(response.response_id)
print(result.messages)

cURL

# Create a response
curl -X POST https://api.lumnis.ai/v1/responses \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "agent\_effort": "medium"
  }'
 
# Check status
curl https://api.lumnis.ai/v1/responses/resp_123456789?wait=30 \
  -H "X-API-Key: your-api-key"

Webhooks (Coming Soon)

Future support for webhooks to receive real-time notifications:

{
  "webhook\_url": "https://yourapp.com/webhooks/lumnis",
  "events": ["response.completed", "response.failed"],
  "secret": "your-webhook-secret"
}

Support

Changelog

v1.0.0 (Current)

  • Initial API release
  • Responses API with async processing
  • Thread management
  • User management
  • External API key management
  • Composio integration for external tools
Quick StartPython SDK