Sol Api Reference

This document describes the live HTTP APIs behind Sol-37 as they exist on this machine on 2026-04-17.

Executive Summary

This document describes the live HTTP APIs behind Sol-37 as they exist on this machine on 2026-04-17. Sol API Reference This document describes the live HTTP APIs behind Sol-37 as they exist on this machine on 2026-04-17. It is intentionally implementation-grounded: endpoint names match the current handlers in random/bin examples use the real public and local URI shapes limits and edge cases come from the running code, not from a wish-list schema API Surface Map Public base: https://sol.system42.one Local service origins: http://127.0.0.1:8895 for chat http://127.0.0.1:8892 for knowledge search http://127.0.0.1:8890 for logbook transport Public reverse-proxied routes: https://sol.system42.one/api/chat https://sol.system42.one/api/chat/query https://sol.system42.one/api/chat/health https://sol.system42.one/api/chat/history https://sol.system42.one/api/chat/reset https://sol.system42.one/api/chat/speak https://sol.system42.one/api/knowledge/query https://sol.system42.one/api/knowledge/health https://sol.system42.one/api/logbook/messages Related machine-readable schemas: https://sol.system42.one/chat-openapi.json https://sol.system42.one/knowledge-openapi.json https://sol.system42.one/privacy.html Related MCP connector surface: https://sol.system42.one/api/mcp/sol https://sol.system42.one/api/mcp/sol/health Authentication: none CORS: chat and knowledge explicitly send permissive CORS headers logbook supports same-origin browser use and preflight, but should still be treated as a site API rather than a generic public cross-origin service MCP note: Sol also exposes a read-only ChatGPT App / MCP connector that fronts the same chat and knowledge stack.

Sol API Reference

This document describes the live HTTP APIs behind Sol-37 as they exist on this machine on 2026-04-17.

It is intentionally implementation-grounded:

API Surface Map

Public base:

Local service origins:

Public reverse-proxied routes:

Related machine-readable schemas:

Related MCP connector surface:

Authentication:

CORS:

MCP note:

Response Conventions

Patterns used across the stack:

1. Sol Chat API

Implementation:

Purpose:

1.1 GET /api/chat/query

Use this for simple text-only calls, GPT Action retrieval-style calls, or copy-pasteable direct URLs.

Accepted query parameters:

- query or message
required text prompt
- profile
optional; reasoning, vision, or vision_fast
- session
optional session id
- persist
optional boolean-ish flag; 1 persists history, default is stateless
- page_context
optional JSON-encoded page context object
- page_title
- page_target
- page_content_type
- page_content
- page_heading
repeatable
- page_question
repeatable

Important limits:

Real URI examples:

- Public:
https://sol.system42.one/api/chat/query?query=What%20is%20Sol%3F
- Public with session persistence:
https://sol.system42.one/api/chat/query?query=Summarize%20the%20current%20system%20state&session=ops-notebook&persist=1
- Public with page grounding:
https://sol.system42.one/api/chat/query?query=Summarize%20this%20page&page_title=Traffic%20Monitor&page_target=%2Fsite-metrics.html&page_content_type=text%2Fhtml&page_content=The%20page%20shows%20visible%20hits%2C%20telemetry%2C%20and%20service%20status.
- Local:
http://127.0.0.1:8895/api/chat/query?query=What%20is%20Sol%3F

Example:

bash
curl -G 'https://sol.system42.one/api/chat/query' \
  --data-urlencode 'query=What is Sol?' \
  --data-urlencode 'session=docs-example' \
  --data-urlencode 'persist=1'

Typical response shape:

json
{
  "message": "Sol is a local-first cognitive annotation system that treats files and logs as the substrate for reasoning.",
  "session": "docs-example",
  "persisted": true,
  "grounded": true,
  "retrieval": {
    "used": true,
    "query": "What is Sol?",
    "warning": null,
    "grounding_mode": "normal",
    "hits": [
      {
        "rank": 1,
        "score": 0.72,
        "path": "/home/david/knowledge/sol-readme.md",
        "doc_key": "/home/david/knowledge/sol-readme.md#0",
        "chunk": 0,
        "text": "Sol is a local-first cognitive annotation system..."
      }
    ],
    "supplemental": {
      "query": "local cognition annotation system files logs reasoning",
      "used": true,
      "warning": null,
      "grounding_mode": "supplemental",
      "hits": [
        {
          "rank": 1,
          "score": 0.61,
          "path": "/home/david/knowledge/sol-architecture.md",
          "doc_key": "/home/david/knowledge/sol-architecture.md#2",
          "chunk": 2,
          "text": "Sol treats files, logs, and local state as a substrate for reasoning..."
        }
      ],
      "source_documents": []
    },
    "source_documents": [
      {
        "path": "/home/david/knowledge/sol-readme.md",
        "resolved_path": "/home/david/knowledge/sol-readme.md",
        "retrieved_snippet": "Sol is a local-first cognitive annotation system...",
        "content_mode": "full_current_file",
        "snippet_found_in_current_file": true,
        "current_file_representation": "raw_file",
        "current_file_content": "Sol is a local-first cognitive annotation system..."
      }
    ]
  },
  "page_context_applied": false,
  "history_size": 3,
  "fallback_grounding_used": false,
  "backend_profile": "reasoning",
  "backend_model_id": "DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf",
  "image_count": 0,
  "query": "What is Sol?",
  "cache_hit": false
}

Notes on retrieval metadata:

Creative-prompt behavior:

Real-world uses:

Failure modes:

1.2 POST /api/chat

Use this for full chat turns, multimodal turns, SSE streaming, or richer page context.

Request body fields:

- message
optional if images is supplied
- session
optional
- persist
boolean, default effectively true for POST requests
- stream
boolean; if true the response is SSE
- profile
optional; reasoning, vision, vision_fast
- page_context
object with:
- target
- title
- content_type
- headings
- suggested_questions
- content
- images
list of image objects
- name
- mime_type
- data_url

Image requirements:

Real URI examples:

- Public JSON turn:
https://sol.system42.one/api/chat
- Local JSON turn:
http://127.0.0.1:8895/api/chat

Example: standard JSON chat turn

bash
curl 'https://sol.system42.one/api/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Give me a grounded two-paragraph explanation of Sol.",
    "session": "docs-post-example",
    "persist": true,
    "stream": false
  }'

Example: page-aware assistant turn

bash
curl 'https://sol.system42.one/api/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Summarize this page and suggest two follow-up questions.",
    "session": "page-summary-demo",
    "persist": false,
    "page_context": {
      "target": "/site-metrics.html",
      "title": "Traffic Monitor",
      "content_type": "text/html",
      "headings": ["Visible Hits", "Archive Counters", "Telemetry"],
      "suggested_questions": ["What changed recently?", "Are any services down?"],
      "content": "This page shows current visible traffic, archive counters, and mirrored service telemetry."
    }
  }'

Example: multimodal POST

bash
curl 'https://sol.system42.one/api/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Describe the visible scene and call out anything unusual.",
    "profile": "vision_fast",
    "persist": false,
    "images": [
      {
        "name": "dashboard-camera.jpg",
        "mime_type": "image/jpeg",
        "data_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
      }
    ]
  }'

Example: SSE streaming

bash
curl 'https://sol.system42.one/api/chat' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "message": "Explain how the knowledge API and chat API fit together.",
    "session": "stream-demo",
    "stream": true
  }'

Streaming event types:

Real-world uses:

1.3 GET /api/chat/health

Use this to verify chat runtime readiness, model routing, and voice availability.

Real URI examples:

- Public:
https://sol.system42.one/api/chat/health
- Local:
http://127.0.0.1:8895/api/chat/health

Example:

bash
curl 'https://sol.system42.one/api/chat/health'

Current live response fields include:

Real-world uses:

1.4 GET /api/chat/history

Loads sanitized message history for a persisted session.

Required query parameter:

Real URI examples:

- Public:
https://sol.system42.one/api/chat/history?session=docs-example
- Local:
http://127.0.0.1:8895/api/chat/history?session=docs-example

Example:

bash
curl -G 'https://sol.system42.one/api/chat/history' \
  --data-urlencode 'session=docs-example'

Response shape:

json
{
  "session": "docs-example",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "What is Sol?"},
    {"role": "assistant", "content": "Sol is a local-first cognitive annotation system..."}
  ],
  "assistant_debug": [
    {
      "grounded": true,
      "fallback_grounding_used": false,
      "page_context_applied": false,
      "backend_profile": "reasoning",
      "backend_model_id": "DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf"
    }
  ]
}

1.5 POST /api/chat/reset

Resets a persisted session.

Request body:

Real URI examples:

- Public:
https://sol.system42.one/api/chat/reset
- Local:
http://127.0.0.1:8895/api/chat/reset

Example:

bash
curl 'https://sol.system42.one/api/chat/reset' \
  -H 'Content-Type: application/json' \
  -d '{"session":"docs-example"}'

Response:

json
{"ok": true, "session": "docs-example"}

1.6 GET or POST /api/chat/speak

Synthesizes reply text to MP3 using the configured voice backend.

Input:

Output:

Real URI examples:

- Public GET:
https://sol.system42.one/api/chat/speak?text=Hello%20from%20Sol
- Local GET:
http://127.0.0.1:8895/api/chat/speak?text=Hello%20from%20Sol
- Public POST target:
https://sol.system42.one/api/chat/speak

Examples:

bash
curl -L 'https://sol.system42.one/api/chat/speak?text=Hello%20from%20Sol' \
  --output sol-hello.mp3
bash
curl 'https://sol.system42.one/api/chat/speak' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Read this aloud in Sol voice."}' \
  --output sol-voice.mp3

Behavior notes:

Common errors:

2. Knowledge Query API

Implementation:

Purpose:

Backing behavior:

2.1 GET /api/knowledge/query

Required query parameters:

Optional query parameters:

- top_k
integer, clamped to 1..12, default 5

Hard limits:

Real URI examples:

- Public:
https://sol.system42.one/api/knowledge/query?query=How%20does%20the%20knowledge%20API%20work%3F&top_k=2
- Local:
http://127.0.0.1:8892/api/knowledge/query?query=How%20does%20the%20knowledge%20API%20work%3F&top_k=2

Examples:

bash
curl -G 'https://sol.system42.one/api/knowledge/query' \
  --data-urlencode 'query=How does the knowledge API work?' \
  --data-urlencode 'top_k=2'
bash
python3 - <<'PY'
import json, urllib.parse, urllib.request
base = 'https://sol.system42.one/api/knowledge/query'
params = urllib.parse.urlencode({'query': 'MasterBot voice playback trials', 'top_k': 3})
with urllib.request.urlopen(f'{base}?{params}') as r:
    data = json.load(r)
print(json.dumps(data, indent=2)[:2000])
PY

Typical response shape:

json
{
  "query": "How does the knowledge API work?",
  "top_k": 2,
  "backend": "openai",
  "cache_path": "/home/david/logs/sol_embeddings.openai.pkl",
  "warning": null,
  "results": [
    {
      "rank": 1,
      "score": 0.83,
      "path": "/home/david/knowledge/sol-site-server.md",
      "chunk": 4,
      "doc_key": "/home/david/knowledge/sol-site-server.md#4",
      "text": "Serves a read-only semantic query endpoint..."
    }
  ]
}

Fallback semantics:

Real-world uses:

Common errors:

Method rule:

2.2 GET /api/knowledge/health

Use this to check that the index is loaded and inspect query-cache metadata.

Real URI examples:

- Public:
https://sol.system42.one/api/knowledge/health
- Local:
http://127.0.0.1:8892/api/knowledge/health

Example:

bash
curl 'https://sol.system42.one/api/knowledge/health'

Current live response fields:

Important caveat:

3. Public Logbook API

Implementation:

Purpose:

Public route shape:

Allowed channels:

Unknown channels are normalized back to public-logbook.

3.1 GET /api/logbook/messages

Query parameters:

- limit
optional, default 80, clamped to 1..250
- channel
optional, default public-logbook

Real URI examples:

- Public latest 20:
https://sol.system42.one/api/logbook/messages?limit=20
- Public alternate channel:
https://sol.system42.one/api/logbook/messages?channel=archive-watch&limit=50
- Local:
http://127.0.0.1:8890/messages?limit=2

Example:

bash
curl -G 'https://sol.system42.one/api/logbook/messages' \
  --data-urlencode 'channel=public-logbook' \
  --data-urlencode 'limit=10'

Typical response:

json
{
  "messages": [
    {
      "id": "1774482631974-f5d49e",
      "name": "davidlones",
      "message": "still alive",
      "created_at": "2026-03-25T23:50:31.974201Z",
      "channel": "public-logbook"
    }
  ],
  "limit": 10,
  "channel": "public-logbook"
}

Real-world uses:

3.2 POST /api/logbook/messages

Creates a logbook message by sending through the IRC-backed transport.

JSON body:

- name
- message
- channel
optional, defaults to public-logbook

Request size rules:

Rate limiting:

Real URI examples:

- Public:
https://sol.system42.one/api/logbook/messages
- Local:
http://127.0.0.1:8890/messages

Example:

bash
curl 'https://sol.system42.one/api/logbook/messages' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sol37",
    "message": "Archive sync complete.",
    "channel": "archive-watch"
  }'

Success response:

json
{
  "ok": true,
  "message": {
    "name": "Sol37",
    "message": "Archive sync complete.",
    "channel": "archive-watch"
  }
}

Common errors:

Real-world uses:

4. Internal-Only Related API

local_dashboard_api.py exists and is important to the Sol stack, but it is not part of the general public external API contract in the same way as chat, knowledge, and logbook.

It should currently be treated as an internal service dependency for:

If you want that surfaced as a stable public API, it should be documented separately as an internal operations API first, then promoted deliberately.

5. Real Integration Recipes

Recipe: direct retrieval, then grounded answer

1. Call:
GET https://sol.system42.one/api/knowledge/query?query=How%20does%20the%20knowledge%20API%20work%3F&top_k=3
2. Inspect the returned results
3. Call:
POST https://sol.system42.one/api/chat
4. Ask for a synthesis or explanation if you want a human-readable answer

Why this is useful:

Recipe: page-aware shell assistant

  1. Capture the current shell page title, target, headings, and compact text
  2. Send them in page_context to POST /api/chat
  3. Ask for summary, explanation, or navigation help

Why this is useful:

Recipe: persistent multi-turn operator session

1. Start with:
POST /api/chat using {"session":"ops-1","persist":true}
2. Continue with the same session id
3. Read back state with:
GET /api/chat/history?session=ops-1
4. Reset with:
POST /api/chat/reset

Recipe: voice playback for a finished assistant answer

  1. Get a response from /api/chat or /api/chat/query
  2. Take the message text
  3. Feed it to /api/chat/speak
  4. Save the MP3 or stream it directly to the browser

Recipe: public logbook monitor

1. Poll:
GET /api/logbook/messages?channel=public-logbook&limit=20
2. Render newest entries
3. Post new lines only when needed, respecting the rate limit

6. Verification Notes

These docs were checked against the current implementation and local contract tests:

They also reflect current live local responses from: