Skip to main content

​
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

EndpointMethodDescription
/api/v1/tasksPOSTSubmit a new task
/api/v1/tasks/streamPOSTSubmit task and get stream URL (201)
/api/v1/tasksGETList tasks with filters
/api/v1/tasks/{id}GETGet task status and result
/api/v1/tasks/{id}/eventsGETGet task event history
/api/v1/tasks/{id}/timelineGETGet Temporal execution timeline

​
Real-Time Streaming

EndpointMethodDescription
/api/v1/stream/sse?workflow_id={id}GETServer-Sent Events stream
/api/v1/stream/ws?workflow_id={id}GETWebSocket stream

​
Session Management

EndpointMethodDescription
/api/v1/sessionsGETList sessions with pagination
/api/v1/sessions/{sessionId}GETGet session details
/api/v1/sessions/{sessionId}/historyGETGet session chat history
/api/v1/sessions/{sessionId}/eventsGETGet session events (grouped by turn)
/api/v1/sessions/{sessionId}PATCHUpdate session title (UUID or external_id)
/api/v1/sessions/{sessionId}DELETEDelete session (soft delete; 204 idempotent)

​
Health & Observability

EndpointMethodDescriptionAuth Required
/healthGETHealth checkNo
/readinessGETReadiness probeNo
/openapi.jsonGETOpenAPI 3.0 specNo

​
Authentication

Development Default: Authentication is disabled (GATEWAY_SKIP_AUTH=1). Enable for production.
When enabled, pass API key via header: 
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.

​
Response Format

All endpoints return JSON with consistent error format: Success (200): 
{
  "task_id": "task-dev-1234567890",
  "status": "COMPLETED",
  "result": "Sentiment: Positive"
}
Error (400/401/404/429/500): 
{
  "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_COMPLETED
  • AGENT_STARTED, AGENT_COMPLETED
  • STATUS_UPDATE, DATA_PROCESSING
  • ERROR_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

Python SDK

Official Python client with streaming support

REST Clients

Use any HTTP client library

​
Next Steps

Submit Tasks

Task submission API

Stream Events

Real-time event streaming

Sessions API

Session management

Python SDK

Get started with Python