API Reference¶

The OSA REST API provides programmatic access to the assistant.

Base URL¶

• Production: https://api.osc.earth/osa
• Development: https://api.osc.earth/osa-dev
• Local: http://localhost:38528

Authentication¶

OSA supports two authentication modes:

Server API Key¶

For server-to-server access using an admin key:

curl -H "X-API-Key: your-server-key" https://api.osc.earth/osa/health

BYOK (Bring Your Own Key)¶

Pass your OpenRouter API key directly. This is the primary method for CLI and widget users:

curl -H "X-OpenRouter-Key: your-openrouter-key" \
  https://api.osc.earth/osa/hed/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What is HED?"}'

When using BYOK, no server API key is required. The user's key is forwarded to the LLM provider.

Endpoints¶

Health Check¶

Check if the API is running.

GET /health

Response:

{
  "status": "healthy",
  "version": "0.7.0",
  "environment": "production"
}

List Communities¶

Get all available communities and their widget configuration.

GET /communities

Response:

[
  {
    "id": "hed",
    "name": "HED (Hierarchical Event Descriptors)",
    "description": "Event annotation standard for neuroimaging research",
    "status": "available",
    "widget": {
      "title": "HED Assistant",
      "initial_message": "Hi! I'm the HED Assistant...",
      "placeholder": "Ask about HED...",
      "suggested_questions": [
        "What is HED and how is it used?",
        "How do I annotate an event with HED tags?"
      ],
      "logo_url": "/hed/logo",
      "theme_color": "#1a365d"
    },
    "links": {
      "homepage": "https://www.hedtags.org",
      "documentation": "https://www.hed-resources.org",
      "repository": "https://github.com/hed-standard"
    }
  }
]

The logo_url field is auto-populated when a logo.* file exists in the community folder, or can be set explicitly in the YAML config. The theme_color field is only present when configured. The links field is null when no links are configured.

This endpoint is public (no authentication required).

Community Logo¶

Serve the community's logo image file.

GET /{community}/logo

Returns the logo file with appropriate Content-Type header. Supported formats: SVG, PNG, JPG, JPEG, WEBP. SVG files include a Content-Security-Policy header (default-src 'none'; style-src 'unsafe-inline') to prevent XSS. Responses are cached for 24 hours (Cache-Control: public, max-age=86400).

Returns 404 if no logo file exists for the community.

This endpoint is public (no authentication required).

Ask¶

Ask a single question to a community assistant.

POST /{community}/ask
Content-Type: application/json
X-OpenRouter-Key: your-key

{
  "question": "How do I annotate a button press in HED?",
  "stream": true
}

Non-streaming Response¶

When stream: false:

{
  "answer": "To annotate a button press in HED...",
  "tool_calls": []
}

Streaming Response (SSE)¶

When stream: true (default):

data: {"event": "content", "content": "To"}

data: {"event": "content", "content": " annotate"}

data: {"event": "tool_start", "name": "retrieve_hed_docs", "params": {...}}

data: {"event": "tool_end", "name": "retrieve_hed_docs", "result": "..."}

data: {"event": "content", "content": "..."}

data: {"event": "done"}

Chat¶

Multi-turn chat with conversation history.

POST /{community}/chat
Content-Type: application/json
X-OpenRouter-Key: your-key

{
  "message": "How do I annotate a button press in HED?",
  "session_id": "optional-session-id",
  "stream": true
}

Non-streaming Response¶

{
  "session_id": "abc123",
  "message": {
    "role": "assistant",
    "content": "To annotate a button press..."
  },
  "tool_calls": []
}

Streaming Response (SSE)¶

data: {"event": "session", "session_id": "abc123"}

data: {"event": "content", "content": "To"}

data: {"event": "tool_start", "name": "retrieve_hed_docs"}

data: {"event": "content", "content": " annotate"}

data: {"event": "done", "session_id": "abc123"}

Mirrors¶

Ephemeral database mirror management. See Database Mirrors for full documentation.

Public Data Feeds¶

Communities can expose two read-only, unauthenticated JSON feeds for building their own frontends (dashboards, widgets, citation badges). Both are opt-in per community via the public_feeds config block and return 404 when the feed is not enabled. Responses are cacheable (Cache-Control: public, max-age=3600).

Currently enabled: EEGLAB (FAQ + citations) and BIDS (citations).

FAQ Feed¶

Synthesized question/answer entries generated from a community's mailing-list and forum archives.

GET /{community}/faq

No authentication required. Returns 404 if public_feeds.faq is not enabled.

Query parameters:

Response:

{
  "community_id": "eeglab",
  "total": 1990,
  "limit": 50,
  "offset": 0,
  "entries": [
    {
      "question": "How do I run ICA in EEGLAB?",
      "answer": "Use runica from the Tools menu...",
      "tags": ["ica", "preprocessing"],
      "category": "how-to",
      "quality_score": 0.95,
      "message_count": 4,
      "first_message_date": "2020-03-11",
      "thread_url": "https://sccn.ucsd.edu/pipermail/eeglablist/..."
    }
  ]
}

total is the count of entries matching the filters (before pagination). Email addresses are redacted from question, answer, and tags.

# Browse the highest-quality how-to entries
curl "https://api.osc.earth/osa/eeglab/faq?category=how-to&min_quality=0.8&limit=10"

# Search
curl "https://api.osc.earth/osa/eeglab/faq?q=ICA%20components"

Citations Feed¶

Per-year citation counts for a community's canonical papers, suitable for a stacked "citations per year" chart. Counts come from OpenAlex (complete and uncapped); a paper's preprint and published versions are merged and deduplicated, and counts are floored at the paper's earliest publication year.

GET /{community}/citations

No authentication required. Returns 404 if public_feeds.citations is not enabled. Takes no query parameters.

Response:

{
  "community_id": "bids",
  "total": 3098,
  "per_year": { "2016": 22, "2017": 48, "...": 0, "2025": 502 },
  "by_paper": {
    "10.1038/sdata.2016.44": { "2016": 22, "2017": 48, "...": 0 },
    "10.1038/s41597-019-0104-8": { "2019": 12, "...": 0 }
  },
  "canonical_dois": ["10.1038/sdata.2016.44", "10.1038/s41597-019-0104-8"],
  "labels": {
    "10.1038/sdata.2016.44": "BIDS (Gorgolewski 2016)",
    "10.1038/s41597-019-0104-8": "EEG-BIDS (Pernet 2019)"
  }
}

curl "https://api.osc.earth/osa/bids/citations"

import httpx

data = httpx.get("https://api.osc.earth/osa/bids/citations").json()
years = sorted(data["per_year"])
for doi, by_year in data["by_paper"].items():
    label = data["labels"].get(doi, doi)
    series = [by_year.get(y, 0) for y in years]
    print(label, series)

Request Parameters¶

Ask Request¶

Chat Request¶

Headers¶

Error Responses¶

401 Unauthorized¶

{
  "detail": "API key required (or provide your own LLM key via BYOK headers)"
}

403 Forbidden¶

{
  "detail": "Invalid API key"
}

500 Internal Server Error¶

{
  "detail": "LLM provider error"
}

Python Client Example¶

import httpx

# Non-streaming
response = httpx.post(
    "https://api.osc.earth/osa/hed/ask",
    json={"question": "What is HED?", "stream": False},
    headers={"X-OpenRouter-Key": "your-key"},
)
print(response.json()["answer"])

import json
import httpx

# Streaming
with httpx.Client() as client:
    with client.stream(
        "POST",
        "https://api.osc.earth/osa/hed/ask",
        json={"question": "What is HED?", "stream": True},
        headers={"X-OpenRouter-Key": "your-key"},
    ) as response:
        for line in response.iter_lines():
            if line.startswith("data: "):
                data = json.loads(line[6:])
                if data["event"] == "content":
                    print(data["content"], end="", flush=True)

cURL Examples¶

Ask (Non-streaming)¶

curl -X POST https://api.osc.earth/osa/hed/ask \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Key: your-key" \
  -d '{"question": "What is HED?", "stream": false}'

Ask (Streaming)¶

curl -N -X POST https://api.osc.earth/osa/hed/ask \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Key: your-key" \
  -d '{"question": "What is HED?"}'

Chat with Session¶

curl -X POST https://api.osc.earth/osa/hed/chat \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Key: your-key" \
  -d '{"message": "What is HED?", "stream": false}'

# Continue conversation with session_id from response
curl -X POST https://api.osc.earth/osa/hed/chat \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Key: your-key" \
  -d '{"message": "Tell me more", "session_id": "abc123", "stream": false}'