Developer Documentation

Everything you need to integrate SovrenAI into your product. Analyze text, write verified content, certify documents, and search — all via REST API.

Quickstart

Classify your first sentence in 30 seconds:

curl -X POST https://sovrenai.ai/api/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"text": "Water boils at 100 degrees Celsius at sea level."}'

Response:

{
  "cus": [{
    "source_text": "Water boils at 100 degrees Celsius at sea level.",
    "tier": 2,
    "tier_name": "Measured",
    "confidence": 0.99,
    "domain": "scientific",
    "word_pills": [...]
  }]
}

That's it. Every sentence gets a rating, a confidence score, and word-level definitions. No AI involved in the classification — it's deterministic.

Python

import requests

response = requests.post("https://sovrenai.ai/api/analyze", json={
    "text": "Water boils at 100 degrees Celsius at sea level."
}, headers={"Authorization": "Bearer YOUR_API_KEY"})

for sentence in response.json()["cus"]:
    print(f'{sentence["tier_name"]:20s} ({sentence["confidence"]:.0%}) | {sentence["source_text"]}')

JavaScript

const resp = await fetch("https://sovrenai.ai/api/analyze", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ text: "Water boils at 100 degrees Celsius." })
});
const { cus } = await resp.json();
cus.forEach(s => console.log(`${s.tier_name} (${Math.round(s.confidence*100)}%) | ${s.source_text}`));

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from Settings > API Key in the app. API access is available on the Pro and Business plans.

The /api/analyze and /api/classify endpoints are also available without authentication for public use (rate limited).

Rate Limits

Rate limits depend on your plan:

Classification endpoints are always free — /api/analyze and /api/classify don't count against your generation limit. Only AI-powered endpoints (chat, compile, ToBi) use generations.

When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header.

Analyze Text FREE

The core of SovrenAI. Send any text, get every sentence classified. No AI, no cost, deterministic results.

{ "text": "Your text here. Multiple sentences work." }

{ "text": "Your text here." }

{ "text": "Your document text here." }

Write & Generate PAID

AI-powered writing with built-in classification. Every generated sentence is verified.

{ "message": "Write a summary of climate change impacts.", "session_id": "your-session-id" }

{ "topic": "quantum computing", "format": "article" }

Certify & Prove PAID

Register documents, generate tamper-evident proofs, compare texts.

{ "text": "Your document text.", "title": "My Report" }

{ "text_a": "First document text.", "text_b": "Second document text." }

{ "text": "Any text." }

{ "tokens": [{"barcode":"WRD-XXXX","word":"hello","type":"word"}, ...] }

Search PAID

{ "query": "quantum computing applications" }

Words & Definitions FREE

Look up any word in the 834K-word verified dictionary.

GET /api/pills/gravity

{ "query": "quantum", "limit": 10 }

Documents PAID

{ "title": "My Report", "content": "Document text..." }

GET /api/documents?limit=20&offset=0

ToBi Agent PAID

Natural language interface to the entire system. Tell ToBi what to do and it executes.

{ "message": "classify this: Water boils at 100 degrees.", "session_id": "my-session" }

Billing FREE

GET /api/billing/status

System FREE

GET /api/health

CLI Tools

194 command-line scripts for development, analysis, and system management. Key ones:

Error Codes

Webhooks

SovrenAI sends webhook events for billing changes. Configure your webhook URL in Settings.