Developer API · Beta

The Shadow-OS agent, as an API

Premium multi-agent reasoning at a fraction of the usual API cost. One REST endpoint, your API key, JSON in & out. A free monthly tier is included — no credit card required.

Fraction of the cost

Premium quality from ultra-efficient models.

One simple endpoint

POST your prompt, get a JSON answer.

Keys you control

Up to 4 keys, revoke anytime.

Your API keys

Loading…

Quickstart

Send a POST request to the endpoint below with your API key in the Authorization header.

POSThttps://shadow-os-backend.onrender.com/api/v1/agent

curl -X POST https://shadow-os-backend.onrender.com/api/v1/agent \
  -H "Authorization: Bearer sk-shadow-..." \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarize the latest AI news", "session_id": "demo"}'

Authentication

Every request must include your secret key — as a Bearer token, or via the X-Shadow-API-Key header. Keep it server-side; never expose it in client-side code.

Authorization: Bearer sk-shadow-...
# or
X-Shadow-API-Key: sk-shadow-...

Request body

inputstringrequiredThe prompt / instruction for the agent.

session_idstringoptionalReuse the same value across calls to keep conversation context.

Response

{
  "answer": "Here is a summary of the latest AI news…",
  "code": null,
  "request_id": "a1b2c3d4",
  "session_id": "demo",
  "usage": { "used": 1, "quota": 75, "remaining": 74, "period": "2026-06" }
}

Endpoints

POST/api/v1/agentRun the agent on a prompt (chat, reasoning, tools). · 1 quota unit

POST/api/v1/uploadUpload a document (pdf/txt/md/csv/docx) into your knowledge base. · 1 quota unit

POST/api/v1/searchSemantic search over your uploaded documents. · 1 quota unit

GET/api/v1/documentsList the documents in your knowledge base. · free

GET/api/v1/usageYour current quota + lifetime usage statistics. · free

Upload a file (multipart):

curl -X POST https://shadow-os-backend.onrender.com/api/v1/upload \
  -H "Authorization: Bearer sk-shadow-..." \
  -F "file=@report.pdf"

Errors

Errors use standard HTTP status codes and return a JSON body with a machine-readable error and a human-readable detail.

{
  "error": "quota_exceeded",
  "detail": "Free monthly quota reached. Resets next month.",
  "request_id": "a1b2c3d4"
}

401invalid_keyMissing or invalid API key.

402quota_exceededFree monthly quota reached.

429rate_limitedToo many requests — retry after a short wait.

400bad_requestMalformed body, or the 'input' field is missing.

Agent Platform API

The pizzeria-style templates are just the easy on-ramp. Under them is a full multi-tenant platform for orgs and developers: configure an agent (persona, knowledge, rules), then drive it with one token that works as a human magic-link, a WhatsApp click-to-chat, and a REST key. Every member gets their own private, persistent memory; knowledge is shared across the org. Strict per-agent isolation, fail-closed.

Run a configured agent

POST {API}/api/agent/run
Content-Type: application/json

{
  "token":      "sk-agent-…",   // the agent token (manager or member)
  "input":      "Do you deliver to Florentin?",
  "member_key": "user-42",       // ← per-PERSON: private memory + history
  "session_id": "main"           // ← conversation id (multi-conversation orgs)
}

member_key — a stable id for each end-user. The agent learns and remembers each one separately (never mixes two people). session_id — keep it constant for one continuous thread, or vary it to run multiple parallel conversations per user. Public agent info: GET /api/agent/info?token=….

Full, durable history (members are not guests): every member’s conversations are saved server-side and listable —GET /api/agent/threads?token=&member_key= lists a member’s conversations;GET /api/agent/history?token=&member_key=&thread_id= returns one conversation’s messages. Both are scoped to that member (fail-closed) — no one reads another member’s threads.

Create & manage agents — with your API key

POST {API}/api/v1/agents
Authorization: Bearer sk-shadow-…

{ "template": "support", "fields": { "business_name": "Acme" },
  "config": { "webhook": "https://you.com/hook", "collect_contact": true } }
→ { "agent": {…}, "manager_token": "sk-agent-…" }   // run it via /api/agent/run

Pure-API lifecycle (Bearer sk-shadow-…):
· POST /api/v1/agents — create · GET /api/v1/agents — list · PATCH /api/v1/agents/:id — persona, rules & full config
· define your own end-users with member_key (each gets private memory + a living profile) · separate chats with session_id
· GET /api/agent/threads · GET /api/agent/history — a user's conversations
· config.webhook — we POST escalation AND outcome events to your server in real time
· config.integrations — connect your own HTTP tools the agent calls mid-chat · config.collect_contact, config.fallback, config.tone, config.require_login, config.memory_mode

With your signed-in session (Bearer JWT) — the full console, by API:
· POST /api/agents/:id/knowledge (text) · POST /api/agents/:id/knowledge/file (PDF/txt/md/csv/docx) · GET/DELETE …/knowledge
· POST /api/agents/:id/tokens (mint, limits) · POST /api/agents/:id/share (opaque links) · GET /api/agents/:id/members (with profiles)
· GET /api/agents/:id/appointments · GET /api/agents/:id/analytics (leads · bookings · quotes · resolved · handoffs)
· GET /api/agents/:id/escalations + stale-customer alerts · POST …/:eid/answer (the human-in-the-loop)

Reference

Access

Registered users only — create keys while signed in

Auth

Header Authorization: Bearer sk-shadow-… (or X-Shadow-API-Key)

Body

input (string, required) · session_id (string, optional — keeps conversation context)

Free quota

75 requests / user / month, then HTTP 402

Rate limit

Max 10 requests / 20s per user → HTTP 429

Keys

Up to 4 active keys per account

Errors

401 invalid key · 402 quota exceeded · 429 rate-limited