Introduction
Shannon provides HTTP REST and gRPC APIs for submitting tasks, streaming results, and managing AI agent workflows.
Base URL: http://localhost:8080 (development)
Quick Start
# Submit a task
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{"query": "Analyze sentiment: Shannon makes AI simple"}'
# Response
{
"task_id": "task-dev-1234567890",
"status": "submitted",
"created_at": "2025-01-20T10:00:00Z"
}
# Stream real-time events
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-1234567890"
API Endpoints
Core Task Operations
| Endpoint | Method | Description |
|---|
/api/v1/tasks | POST | Submit a new task |
/api/v1/tasks/stream | POST | Submit task and get stream URL (201) |
/api/v1/tasks | GET | List tasks with filters |
/api/v1/tasks/{id} | GET | Get task status and result |
/api/v1/tasks/{id}/events | GET | Get task event history |
/api/v1/tasks/{id}/timeline | GET | Get Temporal execution timeline |
Real-Time Streaming
| Endpoint | Method | Description |
|---|
/api/v1/stream/sse?workflow_id={id} | GET | Server-Sent Events stream |
/api/v1/stream/ws?workflow_id={id} | GET | WebSocket stream |
Session Management
| Endpoint | Method | Description |
|---|
/api/v1/sessions | GET | List sessions with pagination |
/api/v1/sessions/{sessionId} | GET | Get session details |
/api/v1/sessions/{sessionId}/history | GET | Get session chat history |
/api/v1/sessions/{sessionId}/events | GET | Get session events (grouped by turn) |
/api/v1/sessions/{sessionId} | PATCH | Update session title (UUID or external_id) |
/api/v1/sessions/{sessionId} | DELETE | Delete session (soft delete; 204 idempotent) |
Health & Observability
| Endpoint | Method | Description | Auth Required |
|---|
/health | GET | Health check | No |
/readiness | GET | Readiness probe | No |
/openapi.json | GET | OpenAPI 3.0 spec | No |
Authentication
Development Default: Authentication is disabled (GATEWAY_SKIP_AUTH=1). Enable for production.
curl -H "X-API-Key: sk_test_123456" \
http://localhost:8080/api/v1/tasks
SSE Streaming: Browser EventSource cannot send custom headers.
- Development: set
GATEWAY_SKIP_AUTH=1 to skip auth.
- Production: initiate SSE from your backend (or edge) and inject
X-API-Key or Authorization: Bearer headers.
- Do not pass API keys in URL query parameters.
{
"task_id": "task-dev-1234567890",
"status": "COMPLETED",
"result": "Sentiment: Positive"
}
{
"error": "Task not found"
}
Rate Limiting
- Default: 60 requests/minute per API key
- Headers:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- 429 Response: Includes
Retry-After header
Event Streaming
Shannon emits 26 event types for real-time monitoring:
Core Events:
WORKFLOW_STARTED, WORKFLOW_COMPLETEDAGENT_STARTED, AGENT_COMPLETEDSTATUS_UPDATE, DATA_PROCESSINGERROR_OCCURRED
LLM Events:
LLM_PROMPT, LLM_OUTPUT, LLM_PARTIAL
Tool Events:
TOOL_INVOKED, TOOL_OBSERVATION
See Event Types Reference for the complete list.
Python SDK: use the EventType enum for filtering and checks. See SDK Streaming.
Client Access
Use the Gateway REST API or the Python SDK (HTTP-only):
- REST endpoints:
http://localhost:8080/api/v1/*
- Python SDK:
ShannonClient(base_url="http://localhost:8080")
Note: gRPC services are internal and not part of the public SDK surface.
Best Practices
1. Use Session IDs for Context
{
"query": "What about Q2?",
"session_id": "user-123-analytics"
}
2. Stream Events for Long Tasks
import requests
r = requests.get(
f"http://localhost:8080/api/v1/stream/sse?workflow_id={task_id}",
stream=True
)
for line in r.iter_lines():
if line:
event = parse_sse(line)
print(event['type'])
3. Handle Rate Limits
import time
def submit_with_retry(query, max_retries=3):
for attempt in range(max_retries):
response = requests.post(url, json={"query": query})
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
continue
return response
4. Use Idempotency Keys
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"query": "Process once"}'
SDKs
Next Steps
