REST API

Direct HTTP API for DriftOS routing and context management.

Base URLs

DriftOS Core (LLM routing):

https://api.driftos.dev/api/v1/llm

DriftOS Embed (Embedding routing):

https://api.driftos.dev/api/v1/embed

Authentication

DriftOS supports three authentication methods:

API Key (Recommended)

Use the x-api-key header with your DriftOS API key:

x-api-key: dft_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bearer Token (API Key)

Alternatively, use the Authorization header with Bearer:

Authorization: Bearer dft_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

JWT Token

Use a Clerk-issued JWT for session-based authentication:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Get your API key: driftos.dev

All three methods work identically - choose what fits your use case.

Endpoints

POST /drift/route

Route a message to a semantic branch.

Request:

POST https://api.driftos.dev/api/v1/embed/drift/route
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "conversationId": "conv-123",
  "message": "I want to plan a trip to Paris"
}

Or using Bearer token:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "action": "BRANCH",
  "branchId": "branch-xyz789",
  "branchTopic": "Paris trip planning",
  "confidence": 0.923,
  "reasoning": "New semantic context detected: travel planning"
}

Fields:

action - Routing decision: STAY, BRANCH, or ROUTE
branchId - Unique identifier for the branch
branchTopic - Human-readable topic label
confidence - Confidence score (0-1)
reasoning - Explanation (Core only)

GET /drift/context/:branchId

Get context for a specific branch.

Request:

GET https://api.driftos.dev/api/v1/embed/drift/context/branch-xyz789
x-api-key: YOUR_API_KEY

Query Parameters:

maxMessages (optional) - Max messages to return (default: 10)
systemPrompt (optional) - Custom system prompt

Response:

{
  "messages": [
    { "role": "user", "content": "I want to plan a trip to Paris" },
    { "role": "assistant", "content": "I'd be happy to help you plan your Paris trip!" }
  ],
  "systemPrompt": "You are a helpful travel assistant.",
  "branchTopic": "Paris trip planning",
  "messageCount": 2,
  "totalMessages": 23,
  "tokenEstimate": 847
}

Example: Complete Flow

# 1. Route a message
curl -X POST https://api.driftos.dev/api/v1/embed/drift/route \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv-123",
    "message": "Tell me about Paris"
  }'

# Response:
{
  "action": "BRANCH",
  "branchId": "branch-abc123",
  "branchTopic": "Paris information",
  "confidence": 0.89
}

# 2. Get context for the branch
curl https://api.driftos.dev/api/v1/embed/drift/context/branch-abc123?maxMessages=10 \
  -H "x-api-key: YOUR_API_KEY"

# Response:
{
  "messages": [
    { "role": "user", "content": "Tell me about Paris" }
  ],
  "systemPrompt": "You are a helpful assistant.",
  "branchTopic": "Paris information"
}

# 3. Use context with your LLM
# (Send messages to OpenAI, Claude, etc.)

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
}

Solution: Check your API key format and ensure it's not revoked.

400 Bad Request

{
  "error": "Missing required field: conversationId"
}

Solution: Ensure all required fields are present.

500 Internal Server Error

{
  "error": "Routing service unavailable"
}

Solution: Retry the request. If the issue persists, check status.driftos.dev.

Rate Limits

Hosted API:

1000 requests/minute per API key
100,000 requests/month (free tier)

Contact support for higher limits.

Next Steps

JavaScript SDK - Use the SDK instead of raw HTTP
Authentication - API key management
Troubleshooting - Fix API issues

REST API

On this page