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 — with fully isolated conversations so every end-user of your app keeps their own private memory and files. A free monthly tier is included — no credit card required.

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

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.

Request body

Response

Files the agent produces

When the agent builds something — a ZIP, a report, code, an image — the response carries it in files. There is no attachment and no multipart body: the signed download_url is the file. Fetch it to get the bytes.

• files is always present — an empty array when the turn produced nothing.
• download_url at the top level is a shortcut to the first file, or null.
• Links are signed and time-limited (exp + sig) — download promptly, or call again for a fresh link.
• Files belong to the session_id that created them (or to your account under scope: "account").

from shadow_os import ShadowOS, AgentConfig

client = ShadowOS()                      # reads $SHADOW_OS_API_KEY

created = client.agents.create(
    name="Nona Pizza",
    template="pizzeria",                 # or persona="..." for full control
    fields={"business_name": "Nona", "hours": "Sun-Thu 11:00-23:00"},
    config=AgentConfig(memory_mode="single", tone="warm and brief"),
)

agent = client.agent(created.id)
agent.knowledge.add_file("menu.pdf", description="Full menu with prices")
agent.knowledge.add_url("https://nona.example/about")

print(agent.share_link().web)            # the link you hand to customers

from shadow_os import AgentClient

with AgentClient("lnk_...") as agent:    # share code or sk-agent- token
    reply = agent.send("Do you deliver to Florentin?", member_key="user-42")
    print(reply.answer, reply.files)

    for conv in agent.for_member("user-42").conversations():
        print(conv.session_id, conv.title)

for c in agent.customers():              # who talked to it, and what it learned
    print(c.display_name, "-", c.profile)

for e in agent.escalations():            # what it could not answer
    agent.answer_escalation(e.id, "Yes - we're open until 23:00 on Sunday.")

print(agent.analytics().raw, agent.appointments(), agent.delivery_status())

Building an app that serves many end-users? Every session_id is a fully isolated conversation — its own memory, its own uploaded files, its own context. Nothing bleeds between your users. This is the default; you don't have to do anything to get it.

Uploads follow the same rule — pass the matching session_id (form field) to /api/v1/upload, /api/v1/search and /api/v1/documents so a file is visible only inside its conversation.

Want one shared assistant instead (a single memory across all your calls, plus your account's connected Gmail/Calendar/integrations)? Add "scope": "account" to the body. An isolated conversation is a clean sandbox and intentionally has no access to your account integrations. Billing and quota always stay on your key, regardless of scope.

# A conversation loads its own messages — no need to work out how to join the two.
for conv in client.conversations.list():
    print(conv.session_id, conv.title)
    for msg in conv.messages():
        print(" ", msg.role, msg.content)

# The same thing, if you already have the id:
for msg in client.conversations.history("thread-id"):
    print(msg.role, msg.content)

client.conversations.rename("thread-id", "Contract review")
client.conversations.delete("thread-id")

mem = client.memory.summary()          # what it has learned about you, across everything
print(mem.summary, mem.count)

client.conversations.progress("thread-id")   # live tool/thinking progress of an in-flight turn

from shadow_os import ShadowOS, Model

client = ShadowOS()

client.chat("Analyse this contract",
            model=Model.google("gemini-2.5-pro", api_key="AIza..."))

client.chat("Draft the reply",
            model=Model.openai("gpt-4o", api_key="sk-..."))

client.chat("Think hard about it",
            model=Model.anthropic("claude-sonnet-4-5", api_key="sk-ant-..."),
            effort="high")

print(client.providers().available)   # what THIS deployment can serve

POST /api/v1/agent
{
  "input": "Analyse this contract",
  "model": {
    "provider": "openai",          // openai | anthropic | google | openai_compatible
    "model":    "gpt-4o",
    "api_key":  "sk-...",          // yours; used for this turn, never stored
    "effort":   "high",            // optional: low | medium | high
    "base_url": "https://..."      // required only for openai_compatible
  }
}

effort is low · medium · high, and is translated to whatever the provider calls reasoning depth — Gemini's thinking_level, OpenAI's reasoning_effort, Claude's thinking budget. It works with or without a model: on its own it just sets the depth of the platform model. Omit it and the depth is chosen per turn from the request itself.

# Ask for it in conversation — this is the normal path.
client.chat("Every weekday at 08:00, email me a summary of my unread mail")

# Then see and control what the agent set up.
for t in client.tasks.list():                 # scheduled work
    print(t.description, t.target_time, t.status)
client.tasks.reschedule(t.id, "2026-10-01T08:00:00")
client.tasks.cancel(t.id)

for w in client.watches.list():               # monitors it created
    print(w.title, w.status, w.interval_minutes)
client.watches.pause(w.id)

for r in client.recipes.list():               # reusable workflows it saved
    print(r.name, r.status)
    for run in client.recipes.runs(r.id):
        print(" ", run.status, run.started_at)

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)
}

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

Send a public URL, a file, a few words — or any mix. The draft is grounded in what you sent: prices, hours and answers are taken from the source, never invented, and missing lists what the source didn't say. Review it, then create the agent with POST /api/agents and add the facts as knowledge.

curl -X POST https://shadow-os-backend.onrender.com/api/agents/draft \
  -H "Authorization: Bearer sk-shadow-..." \
  -F "url=https://your-business.com" \
  -F "file=@price-list.pdf" \
  -F "notes=A pilates studio; help people book a trial class"

→ { "name", "business_type", "summary", "persona", "welcome_message",
    "hours", "prices", "faq": [{ "q", "a" }], "contact", "missing": [ … ] }

Two campaign types: lead_followup (someone asked, then went quiet for days) and win_back (last visit days ago, nothing booked). The agent writes every message itself — for that one person, in the language they write in, from what they actually asked. note is optional guidance in any language.

PUT /api/agents/:id/campaigns
{ "campaigns": [
  { "id": "lead_followup", "type": "lead_followup", "enabled": true, "days": 2,
    "hours": [9, 20], "skip_days": [5], "note": "Mention the free trial class" },
  { "id": "win_back", "type": "win_back", "enabled": true, "days": 30,
    "hours": [9, 20], "skip_days": [5], "note": "" }
] }

POST /api/agents/:id/campaigns/lead_followup/run
→ { "sent": 3, "sent_template": 1, "needs_template": 2, "skipped": 4, "failed": 0 }

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