API Endpoints Reference

Complete reference for all Twig AI REST API endpoints.

Base URL

https://api.twig.so

All endpoints must be accessed over HTTPS.

Authentication

All requests require an API key in the Authorization header:

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

See Authentication for details.

Rate Limits

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

See Rate Limits for details.

API Endpoints

Chat & Completion

POST /api/chat

Generate an AI response.

Request:

{
  "prompt": "What is your refund policy?",
  "agentId": "agent-123",
  "sessionId": "session-456",
  "stream": false
}

Response:

{
  "response": "Our refund policy allows...",
  "sources": [{
    "title": "Refund Policy",
    "url": "https://example.com/refund",
    "relevance": 0.95
  }],
  "metadata": {
    "latency": 1.2,
    "tokensUsed": 1523,
    "strategy": "CEDAR"
  }
}

POST /api/semantic-search

Search without generating response.

Request:

{
  "query": "pricing information",
  "orgId": "org-123",
  "topK": 10
}

AI Agents

GET /api/ai-agent-managers

List all agents.

Response:

{
  "agents": [{
    "id": "agent-123",
    "name": "Support Agent",
    "strategyCode": "CEDAR",
    "status": "ACTIVE"
  }]
}

POST /api/ai-agent-managers

Create new agent.

Request:

{
  "name": "Support Agent",
  "description": "Customer support assistant",
  "strategyCode": "CEDAR",
  "dataSourceIds": ["ds-1", "ds-2"]
}

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

Get agent details.

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

Update agent configuration.

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

Delete agent.

Data Sources

GET /api/data-specs

List data sources.

POST /api/data-specs

Create data source.

Request:

{
  "type": "WEBSITE",
  "name": "Product Documentation",
  "url": "https://docs.example.com",
  "refreshFrequency": "DAILY"
}

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

Trigger processing.

Interactions

GET /api/interactions

List interactions.

Query Parameters:

• limit: Number of results (default: 50)

• offset: Pagination offset

• agentId: Filter by agent

• startDate: Filter by date range

• endDate: Filter by date range

POST /api/interactions/feedback

Submit feedback.

Request:

{
  "interactionId": "int-123",
  "rating": 5,
  "comment": "Very helpful!"
}

Analytics

GET /api/analytics/charts/dashboard

Get analytics dashboard data.

Query Parameters:

• startDate: Start date (YYYY-MM-DD)

• endDate: End date (YYYY-MM-DD)

• agentId: Filter by agent (optional)

Response:

{
  "metrics": {
    "totalQueries": 10250,
    "uniqueUsers": 1523,
    "avgResponseTime": 1.8,
    "satisfactionScore": 4.2
  },
  "trends": {
    "daily": [...]
  }
}

Users & Groups

GET /api/users

List users.

POST /api/user-management/users

Create user.

GET /api/groups

List groups.

POST /api/groups

Create group.

Organization

GET /api/organizations/:id

Get organization details.

PUT /api/organizations/:id

Update organization settings.

Knowledge Base

GET /api/kb

List KB articles.

POST /api/kb

Create article.

PUT /api/kb/:id

Update article.

Error Responses

All errors follow this format:

{
  "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/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

Webhooks

Configure webhooks to receive event notifications.

Supported Events:

• interaction.created

• interaction.completed

• agent.updated

• data_source.processed

See Webhooks for details.

SDKs

Official SDKs available for:

• JavaScript/TypeScript

• Python (coming soon)

See SDKs for documentation.

Next Steps

• REST API Overview - Getting started guide

• Authentication - API key management

• Webhooks - Event notifications

• Rate Limits - Usage limits and optimization