REST API Overview

Programmatic access to agents, data sources, and analytics.

Base URL

https://api.twig.so

Protocol: HTTPS only (HTTP redirects to HTTPS with 301)

API versioning: Path-based (/api/v1/... for new endpoints, /api/... for legacy)

Authentication

All API requests require authentication using an API key:

curl -X GET https://api.twig.so/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for details on generating API keys.

Rate Limits

API requests are rate-limited per organization:

Plan	Requests per Minute	Requests per Day
Free	20	1,000
Pro	100	10,000
Enterprise	1,000+	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

When exceeded, you'll receive a 429 Too Many Requests response.

Response Format

Success Response

{
  "data": {
    "id": "agent-123",
    "name": "Customer Support Agent",
    ...
  },
  "status": "success"
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "Agent not found",
    "details": {
      "agentId": "agent-123"
    }
  },
  "status": "error"
}

Common Error Codes

Code	Status	Description
invalid_request	400	Malformed request
unauthorized	401	Invalid or missing API key
forbidden	403	Insufficient permissions
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
internal_error	500	Server error

Core Endpoints

Chat & Completion

POST /api/chat

Generate an AI response for a given prompt.

curl -X POST https://api.twig.so/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is your refund policy?",
    "agentId": "agent-123",
    "sessionId": "session-456",
    "stream": false
  }'

Response:

{
  "response": "Our refund policy allows returns within 30 days...",
  "sources": [
    {
      "title": "Refund Policy",
      "url": "https://example.com/refund-policy",
      "content": "...",
      "relevance": 0.95
    }
  ],
  "metadata": {
    "latency": 1.2,
    "tokensUsed": 1523,
    "strategy": "CEDAR",
    "confidence": 0.92
  }
}

Agents

GET /api/ai-agent-managers

List all AI agents in your organization.

curl -X GET https://api.twig.so/api/ai-agent-managers \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/ai-agent-managers

Create a new AI agent.

curl -X POST https://api.twig.so/api/ai-agent-managers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Customer support assistant",
    "strategyCode": "CEDAR",
    "dataSourceIds": ["ds-1", "ds-2"]
  }'

GET /api/ai-agent-managers/:id

Get details of a specific agent.

PUT /api/ai-agent-managers/:id

Update an agent's configuration.

DELETE /api/ai-agent-managers/:id

Delete an agent.

Data Sources

GET /api/data-specs

List all data sources.

curl -X GET https://api.twig.so/api/data-specs \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/data-specs

Create a new data source.

curl -X POST https://api.twig.so/api/data-specs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WEBSITE",
    "name": "Product Documentation",
    "url": "https://docs.example.com",
    "refreshFrequency": "DAILY"
  }'

POST /api/data-specs/:id/process

Trigger processing/sync for a data source.

curl -X POST https://api.twig.so/api/data-specs/ds-123/process \
  -H "Authorization: Bearer YOUR_API_KEY"

Interactions

GET /api/interactions

List recent interactions.

curl -X GET https://api.twig.so/api/interactions?limit=50 \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/interactions/feedback

Submit feedback on an interaction.

curl -X POST https://api.twig.so/api/interactions/feedback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactionId": "int-123",
    "rating": 5,
    "comment": "Very helpful!"
  }'

Analytics

GET /api/analytics/charts/dashboard

Get analytics dashboard data.

curl -X GET https://api.twig.so/api/analytics/charts/dashboard?startDate=2024-01-01&endDate=2024-01-31 \
  -H "Authorization: Bearer YOUR_API_KEY"

Advanced Features

Streaming Responses

Enable streaming for real-time response delivery:

curl -X POST https://api.twig.so/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain RAG in detail",
    "agentId": "agent-123",
    "stream": true
  }'

Responses are sent as Server-Sent Events (SSE):

data: {"delta": "RAG stands for", "done": false}
data: {"delta": " Retrieval-Augmented", "done": false}
data: {"delta": " Generation...", "done": false}
data: {"delta": "", "done": true, "sources": [...]}

Semantic Search Only

Retrieve relevant documents without generating a response:

curl -X POST https://api.twig.so/api/semantic-search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pricing information",
    "orgId": "org-123",
    "topK": 10
  }'

Webhooks

Register webhooks to receive events:

curl -X POST https://api.twig.so/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["interaction.created", "agent.updated"],
    "secret": "your-webhook-secret"
  }'

SDKs & Client Libraries

JavaScript/TypeScript

npm install @twig-ai/sdk

import { TwigAI } from '@twig-ai/sdk';

const twig = new TwigAI({ apiKey: process.env.TWIG_API_KEY });

const response = await twig.chat({
  prompt: "What is your refund policy?",
  agentId: "agent-123"
});

console.log(response.text);

Python (Coming Soon)

pip install twig-ai

from twig_ai import TwigAI

twig = TwigAI(api_key=os.environ["TWIG_API_KEY"])

response = twig.chat(
    prompt="What is your refund policy?",
    agent_id="agent-123"
)

print(response.text)

Best Practices

1. Error Handling

Always handle errors gracefully:

try {
  const response = await twig.chat({ prompt, agentId });
  return response;
} catch (error) {
  if (error.code === 'rate_limit_exceeded') {
    // Wait and retry
    await sleep(1000);
    return retry();
  }
  // Log error and handle appropriately
  logger.error(error);
  throw error;
}

2. Rate Limit Management

Implement exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'rate_limit_exceeded' && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. Caching

Cache responses for frequently asked questions:

const cache = new Map();

async function getCachedResponse(prompt, agentId) {
  const cacheKey = `${agentId}:${prompt}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const response = await twig.chat({ prompt, agentId });
  cache.set(cacheKey, response);
  
  return response;
}

4. Session Management

Maintain conversation context with session IDs:

const sessionId = generateSessionId();

// First message
await twig.chat({
  prompt: "What are your pricing plans?",
  agentId: "agent-123",
  sessionId
});

// Follow-up maintains context
await twig.chat({
  prompt: "What's included in the Enterprise plan?",
  agentId: "agent-123",
  sessionId // Same session
});

Next Steps

• API Endpoints Reference - Complete endpoint documentation

• Authentication - API key management

• Webhooks - Event notifications

• SDKs - Client library documentation

• Rate Limits - Detailed rate limit information