# Omni Developer Platform — Full Documentation

> Base URL: https://edge.omnistatic.com

---

# 1. Start Here

## Platform Overview
Omni provides an index-grounded, stateful AI agent platform. It pairs edge routing with an authoritative state engine to deliver low-latency completions, persistent semantic memory, and tool execution.

### Architecture Layers
1. **Clients**: Web application, mobile applications, and the developer CLI (`@omni-os/cli`). Clients render real-time SSE event streams without local agent business logic.
2. **Edge Control Plane (`edge.omnistatic.com`)**: Global edge proxy managing API key validation, rate limits, request parsing, and memory RAG context assembly.
3. **Stateful Agent Engine**: Authoritative reasoning runtime executing multi-step loops, MCP tools, and enforcing the margin-backed credit ledger.
4. **Credential Registry**: Secure, cryptographically hashed credential and permission scope store.

## Quickstart
1. Verify credential:
   `curl -sS https://edge.omnistatic.com/v1/me -H "Authorization: Bearer $OMNI_API_KEY"`
2. Store memory:
   `curl -sS -X POST https://edge.omnistatic.com/v1/memories -H "Authorization: Bearer $OMNI_API_KEY" -H "Content-Type: application/json" -d '{"content":"Project launch is Sept 1"}'`
3. Execute chat completion with memory context injection:
   `curl -sS -X POST https://edge.omnistatic.com/v1/chat/completions -H "Authorization: Bearer $OMNI_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"When is the launch?"}]}'`

## Authentication & Scopes
- Header: `Authorization: Bearer omni_sk_live_<32-hex>`
- Scopes:
  - `chat`: Execute chat completions and list models.
  - `memory:read`: Read and search semantic memories and context.
  - `memory:write`: Create, edit, and delete memories and documents.
  - `usage:read`: Read monthly token consumption and credit balances.
  - `files:write`: Generate presigned upload URLs.
- Dual-tier sliding window rate limits: 60 req/min (per key), 600 req/hr (per principal).

---

# 2. Core Concepts

## Workspaces & Tenancy
- Personal: `projects/<userId>/workspaces/<workspaceId>/`
- Organization [Preview]: `orgs/<orgId>/workspaces/<workspaceId>/`
- No direct bucket access: all storage paths and policies are resolved server-side by the edge proxy.

## Personas & Agents
- Agents are attached to workspaces with defined `personaName`, `vibe`, and `systemPrompt`.
- Dynamic persona swapping via `POST /v1/workspaces/:id/persona/swap`.

## Memory & Context Assembly
- Semantic RAG with vector search across stored user facts and workspace notes.
- Automatic context injection on `/v1/chat/completions` reported via `X-Omni-Shimmer` header.

## Server-Sent Events (SSE) Protocol
Standard stream event sequence:
`thought` -> `tool_call` -> `tool_result` -> `message` -> `done`.

## Credits & Quotas
- Margin-backed central credit ledger.
- Synchronous pre-flight quota admission protecting against unexpected token overruns.

---

# 3. API Reference

- `GET /health` -> `{ status: "ok" }`
- `GET /v1/me` -> `{ ok: true, userId, profile, verifiedAt }`
- `GET /v1/models` -> `{ object: "list", data: [...] }`
- `POST /v1/chat/completions` -> completions / SSE stream
- `GET /v1/memories` -> list memories
- `POST /v1/memories` -> create memory `{ content, metadata }`
- `GET /v1/memories/:id` -> read memory
- `DELETE /v1/memories/:id` -> delete memory
- `POST /v1/memories/search` -> `{ query, limit }`
- `POST /v1/context/build` -> `{ query, workspace_id, limit }`
- `GET /v1/workspaces` -> list workspaces
- `POST /v1/workspaces` -> create workspace `{ name }`
- `POST /v1/workspaces/:workspaceId/documents` -> create/update document
- `POST /v1/workspaces/:workspaceId/files/upload-url` -> generate presigned upload URL
- `GET /v1/workspaces/:workspaceId/chats` -> list chat threads
- `POST /v1/workspaces/:workspaceId/chats` -> create chat thread
- `GET /v1/workspaces/:workspaceId/chats/:threadId/messages` -> read message DAG
- `GET /v1/usage` -> `{ month, usage: { totalTokens, requestCount } }`
- `GET /v1/credits` -> `{ used, limit, remaining, month }`