REST API Reference

For complete endpoint documentation with schemas and try-it-out functionality, see the interactive API reference.

Interactive API Reference Explore all endpoints, view schemas, and test API calls directly in your browser

Code Examples

Complete Workflow (bash)

# 1. Create assistant
ASSISTANT=$(curl -s -X POST http://localhost:8081/api/v1/assistants \
  -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "config": {}}' | jq -r .assistant_id)

# 2. Create thread
THREAD=$(curl -s -X POST http://localhost:8081/api/v1/threads \
  -H "Content-Type: application/json" \
  -d '{"metadata": {}}' | jq -r .thread_id)

# 3. Create run
RUN=$(curl -s -X POST http://localhost:8081/api/v1/runs \
  -H "Content-Type: application/json" \
  -d "{
    \"thread_id\": \"$THREAD\",
    \"assistant_id\": \"$ASSISTANT\",
    \"input\": {\"message\": \"Hello\"}
  }" | jq -r .run_id)

# 4. Stream events
curl -N "http://localhost:8081/api/v1/stream?run_id=$RUN"

# 5. Get final result
curl -s "http://localhost:8081/api/v1/runs/$RUN" | jq

Python

import requests

base_url = "http://localhost:8081/api/v1"

# Create assistant
assistant = requests.post(f"{base_url}/assistants", json={
    "name": "My Assistant",
    "config": {}
}).json()

# Create thread
thread = requests.post(f"{base_url}/threads", json={
    "metadata": {}
}).json()

# Create run
run = requests.post(f"{base_url}/runs", json={
    "thread_id": thread["thread_id"],
    "assistant_id": assistant["assistant_id"],
    "input": {"message": "Hello"}
}).json()

# Get result
result = requests.get(f"{base_url}/runs/{run['run_id']}").json()
print(result)

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

const baseURL = "http://localhost:8081/api/v1"

type Assistant struct {
    AssistantID string                 `json:"assistant_id"`
    Name        string                 `json:"name"`
    Config      map[string]interface{} `json:"config"`
}

type Thread struct {
    ThreadID string                 `json:"thread_id"`
    Metadata map[string]interface{} `json:"metadata"`
}

type Run struct {
    RunID       string                 `json:"run_id"`
    ThreadID    string                 `json:"thread_id"`
    AssistantID string                 `json:"assistant_id"`
    Status      string                 `json:"status"`
    Input       map[string]interface{} `json:"input"`
    Output      map[string]interface{} `json:"output"`
}

func main() {
    // Create assistant
    assistant := createAssistant()
    fmt.Printf("Created assistant: %s\n", assistant.AssistantID)

    // Create thread
    thread := createThread()
    fmt.Printf("Created thread: %s\n", thread.ThreadID)

    // Create run
    run := createRun(thread.ThreadID, assistant.AssistantID)
    fmt.Printf("Created run: %s (status: %s)\n", run.RunID, run.Status)
}

func createAssistant() *Assistant {
    body := map[string]interface{}{
        "name":   "My Assistant",
        "config": map[string]interface{}{},
    }
    data, _ := json.Marshal(body)
    resp, _ := http.Post(baseURL+"/assistants", "application/json", bytes.NewBuffer(data))
    defer resp.Body.Close()

    var assistant Assistant
    json.NewDecoder(resp.Body).Decode(&assistant)
    return &assistant
}

func createThread() *Thread {
    body := map[string]interface{}{"metadata": map[string]interface{}{}}
    data, _ := json.Marshal(body)
    resp, _ := http.Post(baseURL+"/threads", "application/json", bytes.NewBuffer(data))
    defer resp.Body.Close()

    var thread Thread
    json.NewDecoder(resp.Body).Decode(&thread)
    return &thread
}

func createRun(threadID, assistantID string) *Run {
    body := map[string]interface{}{
        "thread_id":    threadID,
        "assistant_id": assistantID,
        "input":        map[string]interface{}{"message": "Hello"},
    }
    data, _ := json.Marshal(body)
    resp, _ := http.Post(baseURL+"/runs", "application/json", bytes.NewBuffer(data))
    defer resp.Body.Close()

    var run Run
    json.NewDecoder(resp.Body).Decode(&run)
    return &run
}

Error Handling

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {
    "field": "Additional context"
  }
}

Common Error Codes:

Status	Error Code	Description
400	invalid_request	Malformed request body
400	validation_error	Field validation failed
401	unauthorized	Missing or invalid auth
404	resource_not_found	Resource doesn’t exist
409	resource_conflict	Resource already exists
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error

Rate Limiting

Rate limit headers included in all responses:

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

When rate limit exceeded:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

Next Steps

• Interactive API Reference - Try endpoints directly
• SSE Streaming - Real-time events
• Python SDK - Python client
• Go SDK - Go client