Shannon AI API Documentation

Overview

Public docs

Everything you need to ship with Shannon's OpenAI and Anthropic compatible API.

Base URL OpenAI-Compatible

https://api.shannon-ai.com/v1/chat/completions

Use the Chat Completions API with function calling and streaming.

Base URL Anthropic-Compatible

https://api.shannon-ai.com/v1/messages

Claude Messages format with tools and anthropic-version header.

Headers Authentication

Authorization: Bearer <your-key>

Or X-API-Key with anthropic-version for Claude-style calls.

Access Status

Public docs - Key required to call

Streaming, function calling, structured outputs, web search.

Launch checklist

+

Point your SDK at Shannon

Set baseURL to the OpenAI or Anthropic endpoints above.

Setup
+

Attach your API key

Use Bearer tokens for OpenAI calls or X-API-Key + anthropic-version.

Security
+

Enable tools & structured outputs

Supports OpenAI tools/functions, JSON schema, and built-in web_search.

Capabilities
+

Track usage

View token and search consumption on this page when signed in to your account.

Analytics

Capabilities

OpenAI + Anthropic

Drop-in replacement for OpenAI and Anthropic APIs with native support for tools, structured outputs, and built-in web search.

Drop-in Replacement

Compatible

Works with OpenAI and Anthropic SDKs. Just change the base URL.

Function Calling

Tools

Define tools, let Shannon call them. Supports auto, forced, and none modes.

Built-in Web Search

Real-time web search with source citations. Automatically available.

Structured Outputs

JSON

JSON mode and JSON Schema enforcement for reliable data extraction.

Multi-turn Tools

Agentic

Automatic function execution loops. Up to 10 iterations per request.

Streaming

Fast

Server-sent events for real-time token streaming.

Quick Start

5 minutes

Get started in three steps. Shannon mirrors OpenAI and Anthropic clients.

Set your base URL

Use the OpenAI-compatible endpoint.

https://api.shannon-ai.com/v1/chat/completions

Add your API key

Use Bearer auth in the Authorization header.

Send your first message

Pick a language and swap in your key.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-1.6-lite",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024
)

print(response.choices[0].message.content)

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'shannon-1.6-lite',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello, Shannon!' }
  ],
  max_tokens: 1024
});

console.log(response.choices[0].message.content);

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("YOUR_API_KEY")
    config.BaseURL = "https://api.shannon-ai.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "shannon-1.6-lite",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "You are a helpful assistant."},
                {Role: "user", Content: "Hello, Shannon!"},
            },
            MaxTokens: 1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

cURL

curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-1.6-lite",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, Shannon!"}
    ],
    "max_tokens": 1024
  }'

Response format

Success Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "Shannon 1.6 Lite",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm Shannon, your AI assistant. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}

API Playground

New

Test the Shannon API directly in your browser. Build your request, run it, and see the response in real-time.

Chat, Responses, Messages

Switch across OpenAI Chat Completions, Responses, and Anthropic Messages without leaving the playground.

Stream live output

Run real requests, inspect raw JSON, and view stream events from the same operator console.

Reuse your key

Signed-in users can pull their Shannon API key straight into the dedicated playground workspace.

/docs/playground

The playground now lives on its own route so the API docs stay Astro-rendered while the request builder remains an explicitly interactive client tool.

Try Playground V2 Get Your API Key

Authentication

All API requests require authentication using your Shannon API key.

OpenAI Format (Recommended)

HTTP

Authorization: Bearer YOUR_API_KEY

Anthropic Format

HTTP

X-API-Key: YOUR_API_KEY
anthropic-version: 2023-06-01

Models

Shannon offers multiple models optimized for different use cases.

shannon-1.6-lite Shannon 1.6 Lite

Fast, efficient responses for everyday tasks

Context 128K

Best For Chat, Q&A, Content Generation

shannon-1.6-pro Shannon 1.6 Pro

Advanced reasoning for complex problems

Context 128K

Best For Analysis, Research, Complex Tasks

shannon-2-lite Shannon 2 Lite

Context 128K

Best For

shannon-2-pro Shannon 2 Pro

Context 128K

Best For

shannon-coder-1 Shannon Coder

Optimized for Claude Code CLI with call-based quota

Context 128K

Best For Code Generation, Tool Use, CLI Integration

Call-based quota

Function Calling

Define tools that Shannon can call to perform actions or retrieve information.

Python

from openai import OpenAI
import json

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

# Define available tools/functions
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g., 'Tokyo'"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="shannon-1.6-lite",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto"
)

# Check if model wants to call a function
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    print(f"Function: {tool_call.function.name}")
    print(f"Arguments: {tool_call.function.arguments}")

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string', description: "City name" },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
        },
        required: ['location']
      }
    }
  }
];

const response = await client.chat.completions.create({
  model: 'shannon-1.6-lite',
  messages: [{ role: 'user', content: "What's the weather in Tokyo?" }],
  tools,
  tool_choice: 'auto'
});

if (response.choices[0].message.tool_calls) {
  const toolCall = response.choices[0].message.tool_calls[0];
  console.log('Function:', toolCall.function.name);
  console.log('Arguments:', toolCall.function.arguments);
}

Tool Choice Options

"auto" Model decides whether to call a function (default)

"none" Disable function calling for this request

{"type": "function", "function": {"name": "..."}} Force a specific function call

Function Call Response

When model calls a function

{
  "id": "chatcmpl-xyz",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Tokyo\", \"unit\": \"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Structured Outputs

Force Shannon to respond with valid JSON that matches your schema.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

# Force JSON output with schema
response = client.chat.completions.create(
    model="shannon-1.6-lite",
    messages=[
        {"role": "user", "content": "Extract: John Doe, 30 years old, engineer"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"}
                },
                "required": ["name", "age", "occupation"]
            }
        }
    }
)

import json
data = json.loads(response.choices[0].message.content)
print(data)  # {"name": "John Doe", "age": 30, "occupation": "engineer"}

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'shannon-1.6-lite',
  messages: [
    { role: 'user', content: 'Extract: John Doe, 30 years old, engineer' }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'person_info',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'integer' },
          occupation: { type: 'string' }
        },
        required: ['name', 'age', 'occupation']
      }
    }
  }
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data); // { name: "John Doe", age: 30, occupation: "engineer" }

Response Format Options

{"type": "json_object"} Force valid JSON output (no specific schema)

{"type": "json_schema", "json_schema": {...}} Force output matching your exact schema

Streaming

Enable real-time token streaming with Server-Sent Events for responsive UIs.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

# Enable streaming for real-time responses
stream = client.chat.completions.create(
    model="shannon-1.6-lite",
    messages=[
        {"role": "user", "content": "Write a short poem about AI"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

// Enable streaming for real-time responses
const stream = await client.chat.completions.create({
  model: 'shannon-1.6-lite',
  messages: [
    { role: 'user', content: 'Write a short poem about AI' }
  ],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

Tip: Streaming responses arrive as Server-Sent Events. Each chunk contains a delta with partial content.

Built-in Web Search

Shannon includes a built-in web_search function that's automatically available.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

# Web search is automatically available!
# Shannon will use it when needed for current information

response = client.chat.completions.create(
    model="shannon-1.6-lite",
    messages=[
        {"role": "user", "content": "What are the latest AI news today?"}
    ],
    # Optionally, explicitly define web_search tool
    tools=[{
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Search the web for current information",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"]
            }
        }
    }]
)

print(response.choices[0].message.content)
# Response includes sources and citations

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

// Web search is automatically available!
// Shannon will use it when needed for current information

const response = await client.chat.completions.create({
  model: 'shannon-1.6-lite',
  messages: [
    { role: 'user', content: 'What are the latest AI news today?' }
  ],
  // Optionally, explicitly define web_search tool
  tools: [{
    type: 'function',
    function: {
      name: 'web_search',
      description: 'Search the web for current information',
      parameters: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search query' }
        },
        required: ['query']
      }
    }
  }]
});

console.log(response.choices[0].message.content);
// Response includes sources and citations

Pro Tip: Web search results include citations. Shannon will automatically cite sources.

Anthropic Format

Shannon also supports Anthropic's Messages API format.

https://api.shannon-ai.com/v1/messages

Python

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/messages"
)

response = client.messages.create(
    model="shannon-1.6-lite",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    # Tool use (Anthropic format)
    tools=[{
        "name": "web_search",
        "description": "Search the web",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"}
            },
            "required": ["query"]
        }
    }]
)

print(response.content[0].text)

JavaScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/messages'
});

const response = await client.messages.create({
  model: 'shannon-1.6-lite',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ],
  // Tool use (Anthropic format)
  tools: [{
    name: 'web_search',
    description: 'Search the web',
    input_schema: {
      type: 'object',
      properties: {
        query: { type: 'string' }
      },
      required: ['query']
    }
  }]
});

console.log(response.content[0].text);

Required Header: Anthropic format requires anthropic-version: 2023-06-01.

SDKs

Compatible

Use any OpenAI or Anthropic SDK - just change the base URL.

OpenAI-Compatible SDKs

SDK Python

Official OpenAI Python SDK - works with Shannon

pip install openai

View Docs ->

SDK JavaScript / TypeScript

Official OpenAI Node.js SDK - works with Shannon

npm install openai

View Docs ->

SDK Go

Community Go client for OpenAI-compatible APIs

go get github.com/sashabaranov/go-openai

View Docs ->

SDK Ruby

Community Ruby client for OpenAI-compatible APIs

gem install ruby-openai

View Docs ->

SDK PHP

Community PHP client for OpenAI-compatible APIs

composer require openai-php/client

View Docs ->

SDK Rust

Async Rust client for OpenAI-compatible APIs

cargo add async-openai

View Docs ->

Anthropic-Compatible SDKs

SDK Python (Anthropic)

Official Anthropic Python SDK - works with Shannon

pip install anthropic

View Docs ->

SDK TypeScript (Anthropic)

Official Anthropic TypeScript SDK - works with Shannon

npm install @anthropic-ai/sdk

View Docs ->

Error Handling

Shannon uses standard HTTP status codes and returns detailed error messages.

400 Bad Request Invalid request format or parameters

401 Unauthorized Invalid or missing API key

402 Quota Exceeded Token or search quota exceeded

429 Rate Limited Too many requests, slow down

500 Server Error Internal error, retry later

Error Response Format

Error Response

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Changelog

LOG

Recent updates and improvements to the Shannon API.

v2.1.0

2025-01-03

New Added shannon-coder-1 model for Claude Code CLI integration
New Call-based quota system for Coder model
Improved Improved function calling reliability

v2.0.0

2024-12-15

New Added Anthropic Messages API compatibility
New Multi-turn tool execution (up to 10 iterations)
New JSON Schema response format support
Improved Enhanced web search with better citations

v1.5.0

2024-11-20

New Added shannon-deep-dapo model for complex reasoning
New Built-in web_search function
Improved Reduced latency for streaming responses

v1.0.0

2024-10-01

New Initial API release
New OpenAI-compatible chat completions endpoint
New Function calling support
New Streaming via Server-Sent Events

Your API Key

Access

Use Bearer tokens for OpenAI calls or X-API-Key + anthropic-version.

YOUR_API_KEY

Get Your API Key

Keep your API key secret. Regenerating creates a new key and invalidates the old one.

Your Usage

View token and search consumption on this page when signed in to your account.

-- API Calls

-- Tokens Used

Shannon API

Overview

Capabilities

Drop-in Replacement

Function Calling

Built-in Web Search

Structured Outputs

Multi-turn Tools

Streaming

Quick Start

Set your base URL

Add your API key

Send your first message

Response format

API Playground

Chat, Responses, Messages

Stream live output

Reuse your key

Authentication

OpenAI Format (Recommended)

Anthropic Format

Models

Function Calling

Tool Choice Options

Function Call Response

Structured Outputs

Response Format Options

Streaming

Built-in Web Search

Anthropic Format

SDKs

OpenAI-Compatible SDKs

Anthropic-Compatible SDKs

Error Handling

Error Response Format

Changelog

Your API Key

Your Usage

Shannon Coder (shannon-coder-1)

Ready to Build?