API Endpoints Reference

API endpoints for querying agents, managing data sources, and retrieving analytics.

Base URL

https://api.twig.so

Protocol: HTTPS only (HTTP requests redirect to HTTPS)

API Version: v1 (included in path: /api/v1/... or legacy /api/...)

Authentication

Include API key in Authorization header:

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

Key format: twigsk_live_... (production) or twigsk_test_... (test)

Generate key: Settings → API Keys → Generate New Key

See Authentication for key management.

Rate Limits

Enforced per API key:

Scope	Requests/Minute	Burst Allowance
Execute (queries)	100	120
Write (create/update)	10	15
Read (list/get)	200	250
Admin (org settings)	50	60

Headers in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1610708100

When exceeded: 429 Too Many Requests with reset timestamp

See Rate Limits for optimization strategies.

API Endpoints

Chat & Completion

POST /api/v1/query

Generate agent response. Replaces legacy /api/chat.

Request:

{
  "agent_id": "agent_abc123",
  "query": "What is your refund policy?",
  "session_id": "sess_xyz789",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 500
}

Required fields: agent_id, query

Optional fields:

• session_id: For multi-turn conversations (creates new if omitted)

• stream: Boolean, SSE streaming (default: false)

• temperature: 0-2 (default: agent config value)

• max_tokens: Response length limit (default: agent config value)

Response (200 OK):

{
  "response": "Our refund policy allows returns within 30 days...",
  "sources": [{
    "chunk_id": "chk_abc123",
    "document_title": "Refund Policy",
    "document_url": "https://example.com/refund",
    "similarity_score": 0.89,
    "chunk_text": "Refunds are processed within..."
  }],
  "metadata": {
    "interaction_id": "int_xyz456",
    "latency_ms": 1432,
    "tokens_input": 523,
    "tokens_output": 145,
    "cost_usd": 0.0042,
    "rag_strategy": "cedar",
    "model": "gpt-4"
  }
}

Error responses:

• 400: Missing required field, invalid agent_id format

• 401: Invalid API key

• 403: API key lacks Execute scope

• 404: Agent not found

• 429: Rate limit exceeded

• 500: Internal error

Latency: 1-5s depending on RAG strategy

POST /api/v1/semantic-search

Retrieve chunks without LLM generation.

Request:

{
  "query": "pricing information",
  "org_id": "org_123",
  "top_k": 10,
  "similarity_threshold": 0.7,
  "data_source_ids": ["ds_1", "ds_2"]
}

Required: query, org_id

Response (200 OK):

{
  "chunks": [{
    "chunk_id": "chk_abc123",
    "text": "Pricing starts at $99/month...",
    "similarity_score": 0.85,
    "document_id": "doc_456",
    "document_title": "Pricing Page"
  }],
  "query_embedding": [0.123, -0.456, ...],
  "metadata": {
    "total_chunks_searched": 15234,
    "latency_ms": 234
  }
}

Agents

GET /api/v1/agents

List agents. Requires Read scope.

Query params:

• limit: Max results (default: 50, max: 200)

• offset: Pagination (default: 0)

Response (200):

{
  "agents": [{
    "id": "agent_abc123",
    "name": "Support Agent",
    "rag_strategy": "cedar",
    "model": "gpt-4",
    "status": "active",
    "data_source_ids": ["ds_1", "ds_2"],
    "created_at": "2024-01-15T10:30:00Z"
  }],
  "total": 5,
  "limit": 50,
  "offset": 0
}

POST /api/v1/agents

Create agent. Requires Write scope.

Request:

{
  "name": "Support Agent",
  "system_prompt": "You are a helpful support assistant.",
  "rag_strategy": "cedar",
  "model": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 500,
  "data_source_ids": ["ds_1", "ds_2"]
}

Required: name, data_source_ids

Response (201): Agent object with generated id

GET /api/v1/agents/:id

Get agent details. Requires Read scope.

PUT /api/v1/agents/:id

Update agent. Requires Write scope.

Request: Same fields as POST, all optional

Response (200): Updated agent object

DELETE /api/v1/agents/:id

Delete agent. Requires Write scope.

Response (204): No content

Data Sources

GET /api/v1/data-sources

List data sources. Requires Read scope.

Query params: limit, offset, status (active/processing/failed)

POST /api/v1/data-sources

Create data source. Requires Write scope.

Request:

{
  "type": "website",
  "name": "Product Documentation",
  "config": {
    "url": "https://docs.example.com",
    "max_pages": 1000
  },
  "sync_frequency": "daily"
}

Types: website, file, confluence, slack, google_drive, sharepoint

Sync frequency: hourly, daily, weekly, manual

Response (201): Data source object with ID, status "pending"

POST /api/v1/data-sources/:id/sync

Trigger sync. Requires Write scope.

Response (202): Sync job queued

GET /api/v1/data-sources/:id/status

Check processing status.

Response:

{
  "status": "processing",
  "chunks_indexed": 450,
  "progress_pct": 75,
  "estimated_completion": "2024-01-15T10:45:00Z"
}

Interactions

GET /api/v1/interactions

List query history. Requires Read scope.

Query params:

• limit, offset: Pagination

• agent_id: Filter by agent

• start_date, end_date: Date range (YYYY-MM-DD)

• feedback: Filter by positive/negative/null

Response:

{
  "interactions": [{
    "id": "int_xyz123",
    "agent_id": "agent_abc",
    "query": "What is pricing?",
    "response": "Pricing starts at...",
    "feedback": "positive",
    "latency_ms": 1432,
    "created_at": "2024-01-15T10:30:00Z"
  }],
  "total": 1250
}

POST /api/v1/interactions/:id/feedback

Submit feedback. Requires Execute scope.

Request:

{
  "feedback": "positive",
  "comment": "Very helpful!"
}

feedback values: positive, negative

Analytics

GET /api/v1/analytics

Get metrics. Requires Admin scope.

Query params:

• start_date, end_date: Date range (required, YYYY-MM-DD)

• agent_id: Filter by agent (optional)

• granularity: hour, day, week, month (default: day)

Response:

{
  "metrics": {
    "total_queries": 10250,
    "unique_users": 1523,
    "avg_latency_ms": 1843,
    "accuracy_rate": 0.82,
    "citation_rate": 0.91,
    "total_cost_usd": 42.50
  },
  "time_series": [{
    "timestamp": "2024-01-15T00:00:00Z",
    "queries": 450,
    "latency_p50": 1432,
    "latency_p95": 2890
  }]
}

Users

GET /api/v1/users

List users. Requires Admin scope.

POST /api/v1/users

Create user. Requires Admin scope.

Request:

{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "train"
}

Roles: readonly, train, configure, admin

Knowledge Base

GET /api/v1/kb

List KB articles. Requires Read scope.

Query params: status (draft/published), limit, offset

POST /api/v1/kb

Create KB article. Requires Write scope.

Request:

{
  "title": "How to reset password",
  "content": "Steps: 1. Click Forgot Password...",
  "tags": ["auth", "password"],
  "status": "published"
}

PUT /api/v1/kb/:id

Update article. Creates new version. Requires Write scope.

Error Responses

Standard format:

{
  "error": {
    "code": "invalid_request",
    "message": "Agent not found",
    "details": {
      "agent_id": "agent_123",
      "org_id": "org_456"
    }
  },
  "request_id": "req_xyz789"
}

request_id: Include when contacting support

Error Codes

HTTP Status	Code	Description	Action
400	invalid_request	Missing required field, invalid format	Check request body against docs
401	unauthorized	Invalid/missing API key	Verify key format, regenerate if needed
403	forbidden	Insufficient scope	Check key permissions (Settings → API Keys)
404	not_found	Resource doesn't exist	Verify ID, check resource wasn't deleted
429	rate_limit_exceeded	Too many requests	Wait for reset (check X-RateLimit-Reset header)
500	internal_error	Server error	Retry with exponential backoff, contact support if persists
503	service_unavailable	Maintenance or overload	Retry after 5-10 minutes

Retry logic: Use exponential backoff for 429, 500, 503 errors. Do NOT retry 400, 401, 403, 404.

Webhooks

Receive event notifications via HTTP POST to your endpoint.

Configure: Settings → Webhooks → Add Endpoint

Events:

• interaction.completed: Query processed, response generated

• data_source.synced: Data source sync finished

• agent.updated: Agent configuration changed

• eval.completed: Evaluation run finished

Payload example:

{
  "event": "interaction.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "interaction_id": "int_xyz123",
    "agent_id": "agent_abc",
    "latency_ms": 1432
  }
}

Security: Webhook signature in X-Twig-Signature header (HMAC-SHA256)

See Webhooks Guide for verification and retry logic.

SDKs

TypeScript/JavaScript:

npm install @twig/sdk

Python:

pip install twig-sdk

Usage example (TypeScript):

import { TwigClient } from '@twig/sdk';

const client = new TwigClient({ apiKey: process.env.TWIG_API_KEY });

const response = await client.query({
  agentId: 'agent_abc123',
  query: 'What is pricing?'
});

console.log(response.response);

See SDK Documentation for full API reference.

Next Steps

• Authentication Guide - API key generation and rotation

• Rate Limiting - Optimization strategies, caching

• Webhooks Setup - Event-driven integrations

• SDK Reference - Client library docs