> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/libra-os/capabilities.md). # Capabilities A single map of everything Libra OS can do, grouped by what you're trying to accomplish. Each capability lists the endpoint(s) that drive it and where to go for the full reference. Libra OS exposes its features over HTTP in two shapes: * **Anthropic-compatible** — `POST /v1/messages` and the managed-agents endpoints under `/v1/agents`. Point the official Anthropic SDK at your instance and existing code works unchanged. See [Anthropic SDK Quickstart](/libra-os/anthropic-sdk-quickstart.md). * **Native chat** — `POST /agents/v1/{api_key}/chat` and the OpenAI-compatible `POST /v1/chat/completions`. Adds Libra-specific options (fast mode, per-call streaming events, aggregated token usage). > **Source of truth:** the full request/response schema for every managed endpoint lives in the OpenAPI spec shipped with the [Libra OS SDK](https://github.com/libraos/sdk) (`openapi/libra-os-partner.v1.yaml`). This page is the human index over that contract. *** ## Integrating with AI tools vs. by hand Both integration styles discover the same surface — pick per task, or mix them. **AI-assisted integration** (Claude Code, Cursor, or your own agents writing the glue code): give your tool the machine-readable contract instead of prose docs. | What | Where | Use it for | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OpenAPI contract | [`openapi/libra-os-partner.v1.yaml`](https://github.com/libraos/sdk/blob/main/openapi/libra-os-partner.v1.yaml) in the SDK repo | Full request/response schemas — fetchable at a stable raw URL, so an AI tool can ingest it directly. | | Runtime capability discovery | `GET /v1/managed/deployment` | What **this** instance actually has enabled: capabilities, model tiers, locales, auth contract. Call it first — features vary per deployment. | | MCP endpoint | `POST /api/mcp` (JSON-RPC) | Let an approved AI client enumerate Libra OS tools (`tools/list`), call a governed tool, or read declared resources. Off by default — the operator enables it per instance. | | Agent schema | `GET /v1/agents/schema` | Machine-readable `AgentDef` JSON Schema — lets a tool generate valid agent definitions. | | This page | `docs.meganova.ai` | Plain Markdown — paste the URL into your AI tool as a task-oriented index over the contract. | **Traditional integration**: the endpoint tables below, the SDK's typed clients and CLI, and the worked examples in the [SDK repo](https://github.com/libraos/sdk). For app **frontends** (as opposed to integration tooling), Libra OS also streams AG-UI events at `/api/copilotkit/*` — live message deltas, tool-call events, and UI state for interactive UIs. *** ## Chat & agents Talk to agents, and create or manage them through the API. | Capability | Endpoint | What it does | | ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Chat with an agent | `POST /agents/v1/{api_key}/chat` | Native chat. Supports `fast`, `stream`, per-call `metadata` (streaming events, max tokens). | | Anthropic-compatible message | `POST /v1/messages` | Drop-in for the Anthropic Messages API. | | OpenAI-compatible completion | `POST /v1/chat/completions` | Drop-in for OpenAI clients; auto-detects report requests; real `finish_reason` + `usage`. | | Create an agent | `POST /v1/agents` | Register a new agent or persona from JSON. | | List / get agents | `GET /v1/agents`, `GET /v1/agents/{id}` | Enumerate agents; read one (`agent_type`, `brain`, `capabilities`, `guardrails`, …). | | Update an agent | `PUT /v1/agents/{id}` | Partial update (PATCH-merge semantics). | | Delete an agent | `DELETE /v1/agents/{id}` | Remove a runtime agent. | | Agent JSON Schema | `GET /v1/agents/schema` | The machine-readable `AgentDef` schema for validation. | | Persona manifest | `GET /agents/v1/personas`, `GET /agents/v1/personas/{id}` | Boot-time persona list with ETag round-trip; fetch one persona. | | Count tokens | `POST /v1/messages/count_tokens` | Anthropic-compatible token counting without running a completion. | | List models | `GET /v1/models` | OpenAI-compatible model roster this instance will accept. | A minimal chat call: ```bash curl -X POST "$LIBRA_OS_URL/agents/v1/$API_KEY/chat" \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"Summarize our Q3 contract terms."}]}' ``` *** ## Knowledge & documents Upload your own files, index them into a searchable knowledge base, and retrieve grounded answers. | Capability | Endpoint | What it does | | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Upload a document | `POST /v1/managed/documents/upload` | Upload a PDF / Word / Markdown / text file; auto-indexed. | | List / delete documents | `GET /v1/managed/documents`, `DELETE /v1/managed/documents/{id}` | Manage documents in a collection. | | Hybrid search | `POST /v1/managed/knowledge/search` | Vector + keyword search across the knowledge base. | | Ingest into a collection | `POST /v1/managed/knowledge/ingest` | Add a document to a named knowledge collection. | | List collections | `GET /v1/managed/knowledge/collections` | Enumerate every knowledge collection. | | OCR a scanned PDF / image | `POST /v1/managed/documents/ocr` | Vision-model OCR for image-only PDFs; returns markdown + page count + cost. | | Extract text (office docs) | `POST /v1/managed/documents/extract` | Native text extraction for DOCX / XLSX / ODT / PDF-with-text / CSV / EML and more — no vision model. | See [Documents & Knowledge](/libra-os/documents-and-knowledge.md) for the upload → search → cite → delete workflow. *** ## Reports & research Generate long-form, evidence-backed deliverables over your knowledge base and the live web. | Capability | How to trigger | What it does | | ---------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Structured report | `generate_report` tool or `/report` (auto-detected on `POST /v1/chat/completions`) | Multi-section, cited report (outline → sections → risk matrix → timeline → summary) with inline `[source:chunk]` citations. Streams progress. | | Deep / multi-source research | `research_query` and `deep_research` (web-search skills) | High-accuracy web research with citation synthesis; optional live web enrichment. | Reports stream as SSE deltas and emit a final markdown document. Poll status at `GET /api/reports/status/{id}`. ### Single-shot web search (no agent) For a plain "just search the web" lookup you don't need an agent, the planner, or streaming — call the web skill's tools **directly**. One round-trip, deterministic JSON output, same JWT/api-key auth as chat: | Tool | Call | Body | | ---------------------- | ----------------------------------------- | --------------------------------------------------- | | Fast/cheap search | `POST /api/skills/web/search_web/run` | `{"query":"…"}` | | High-accuracy research | `POST /api/skills/web/research_query/run` | `{"query":"…","depth":"advanced","max_results":10}` | | Fetch a URL | `POST /api/skills/web/fetch_url/run` | `{"url":"…"}` | ```bash curl -X POST "$LIBRA_OS_URL/api/skills/web/search_web/run" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"query":"latest EU AI Act timeline"}' # -> {"output":"{\"query\":…,\"results\":[{\"title\":…,\"url\":…,\"content\":…}]}"} ``` Use this when you want the result, not a conversation. The agent/report paths above are for when search feeds a larger reasoning or drafting task. *** ## Memory & personalization Make agents remember context across sessions and reflect how your organization works — without storing raw chat transcripts. | Capability | How it works | What it does | | ---------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Observational memory | Enable per-instance; keyed per `(platform user, end user, agent)` | Agents recall prior facts across sessions from a condensed memory log, not a transcript. | | Persisted fields | Agent declares `output_type.persist_fields` | Auto-persists structured slot values across turns and re-injects them as known context. | | House profile | Per-employee markdown policy | Injects a house playbook / style / escalation block into every agent that employee owns. | | Read an agent's memory | `GET /v1/managed/memory?agent_id=…&scope=…` | Read the caller's own observational-memory log for one persona (corporate or personal scope). Returns `200` with empty content when nothing is remembered yet. | | Edit house profile | `GET/PUT /v1/managed/employees/{id}/house-profile` | Admin read/write of the per-employee house profile (supports `If-Match` concurrency). | *** ## Voice & media A full record → transcribe → answer → speak loop, plus image generation. | Capability | Endpoint | What it does | | ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------ | | Speech-to-text | `POST /v1/audio/transcriptions` | Transcribe audio (Whisper or an audio-LLM) with timestamps. | | Text-to-speech | `POST /v1/audio/speech` | Synthesize spoken audio from text. | | Realtime voice | `GET /v1/realtime` (WebSocket) | Full-duplex speech-to-speech over a streaming connection. | | Image generation | `POST /v1/images/generations` | OpenAI-compatible image generation (client picks the model). | | Image edits / variations | `POST /v1/images/edits`, `POST /v1/images/variations` | Multipart image editing and variations. | *** ## Async jobs Run long operations (deep research, multi-section reports) in the background and stream progress. | Capability | Endpoint | What it does | | ---------------- | ----------------------------------------------------------------- | ----------------------------------------------------- | | Submit a job | `POST /v1/managed/agents/jobs` | Queue an async agent run; returns a `job_id`. | | List / get a job | `GET /v1/managed/agents/jobs`, `GET /v1/managed/agents/jobs/{id}` | Track status and result. | | Stream a job | `GET /v1/managed/agents/jobs/{id}/stream` | SSE with `Last-Event-ID` replay, live until terminal. | | Cancel a job | `DELETE /v1/managed/agents/jobs/{id}` | Graceful drain. | *** ## Approvals & governance Human-in-the-loop control over side-effecting agent actions, and field-level access policy. These are opt-in features — check `GET /v1/managed/deployment` for availability on your instance. | Capability | Endpoint | What it does | | -------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Pending-action queue | `GET /v1/managed/actions`, `GET …/actions/{id}` | List/read actions parked for approval — a high-risk tool call runs a dry-run and waits here instead of executing. | | Approve / reject / claim | `POST /v1/managed/actions/{id}/approve` (`…/reject`, `…/claim`) | Decide a pending action; approve fires the real webhook exactly once. Claim soft-locks it to a reviewer. | | Park an external action | `POST /v1/managed/actions` | Let a connector or external system queue an action for approval, with a snapshotted callback. | | Departmental queues | `GET/POST/DELETE /v1/managed/groups…`, `GET …/groups/mine` | Group registry (member / approver / lead roles). Actions tagged with a `group_id` become visible and decidable by that group, not just admins. | | Field-level access policy | `GET/POST/PUT/DELETE /v1/managed/field-policies…` | Declare per-role field visibility rules; `POST …/field-policies/{type}/evaluate` is the canonical strip/filter reference. | | Field-access audit | `GET /v1/managed/field-access-events` | Query the audit trail of field-policy decisions. | | Knowledge curation signals | `GET /v1/managed/knowledge-signals`, `…/candidates` | Review agent-reported knowledge gaps and the fact keys that cleared the promotion quorum. | *** ## Connectors Wire Libra OS to external systems the operator has credentialed. | Capability | Endpoint | What it does | | -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Manage connectors | `GET/PUT/DELETE /v1/managed/connectors/{kind}` | Configure a connector (e.g. Slack, SharePoint, support-desk) with encrypted-at-rest credentials. | | Connector status | `GET /v1/managed/connectors`, `…/{kind}/credentials`, `…/sharepoint/sync-status` | Enumerate configured connectors and check sync health. | | Custom-tool webhooks | Declared per agent (`custom_tools`) | Point an agent's tool at your own HTTPS endpoint; calls are HMAC-signed, and side-effecting tools can be routed through the approval queue above. | *** ## Employees & portability Bundle an agent (or a whole digital employee) and move it between instances. | Capability | Endpoint | What it does | | ---------------- | ---------------------------------------------- | ----------------------------------------------------------------------- | | Manage employees | `POST/GET/PUT/DELETE /v1/managed/employees` | CRUD for digital employees and the agents they own. | | Export a bundle | `GET /v1/managed/employees/{id}/bundle/export` | Download a portable `.nova-bundle.zip` (employee + agents + knowledge). | | Import a bundle | `POST /v1/managed/employees/bundle/import` | Re-create an employee on another instance (idempotent, re-embeds). | *** ## Sessions, users & auth Multi-tenant identity, native sessions, and single sign-on. | Capability | Endpoint | What it does | | ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | Native sessions | `POST /v1/managed/sessions`, `GET /v1/managed/sessions/{id}` | Create and read Libra OS native sessions. | | Manage users | `POST/GET/DELETE /v1/managed/users` | CRUD for platform users (default password + first-sign-in reset). | | Single sign-on (provider) | `/oauth/*` | Built-in OIDC provider — let LibreChat, Chatwoot, or any OIDC client delegate login to Libra OS. | | Sign in with external IdP | `/oauth` login form | Relying-party broker for Google / Okta / Azure / Authentik / GitHub. | | Service-to-service tokens | `POST /oauth/token` (`client_credentials`) | Machine-to-machine JWTs for operator-registered service clients — no user in the loop. | | Service API keys | `POST /api/service-keys` (+ `…/self`), `GET`, `DELETE` | Long-lived `nk_` keys for backend callers; `…/self` lets any authenticated user mint an inference-scoped key. | | Per-agent API keys | `POST /api/agents/{id}/keys` | Scoped `nk_` keys that can only call one agent. | | SCIM provisioning | `/scim/v2/*` | SCIM 2.0 user provisioning from Entra ID / Okta; deactivated users lose access within the revocation window. | See the [Admin Guide](/libra-os/admin-guide.md) for tenant setup, and the SDK's `oidc-client-flow` doc for the delegated-login dance. *** ## Files & workspaces Per-session file workspaces agents can read and write. | Capability | Endpoint | What it does | | ---------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- | | List workspace files | `GET /v1/managed/filesystem/{tenant}/{session}/files` | Enumerate a session's files. | | Read / write / delete a file | `GET/PUT/DELETE …/files/{path}` | Manage individual files (raw bytes). | | Upload standalone files | `POST /v1/files`, `GET/DELETE /v1/files/{id}` | OpenAI-compatible file upload and retrieval. | | Chat attachments | `POST /v1/conversations/{cid}/attachments`, `GET …/{aid}/download` | Attach files to a conversation and download them later. | *** ## Admin, ops & extensibility Operate the instance and extend it with webhooks. | Capability | Endpoint | What it does | | --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Instance capabilities | `GET /v1/managed/deployment` | Read this instance's capabilities, model tiers, locales, and auth contract — discover what a given deployment supports before you call it. | | Platform settings | `GET/PUT /v1/managed/settings`, `…/settings/{key}` | Read/write runtime settings (most config lives in the DB, env vars win). | | Lifecycle hooks | `GET/POST /v1/managed/hooks`, `…/hooks/{id}` | Register webhook subscriptions for lifecycle events. | | Custom-tool results | `POST /v1/managed/agents/messages/{id}/custom_tool_results` | Return a result for a partner-defined custom tool (inline tool-use). | | Server logs | `GET /v1/managed/logs` | Admin read of recent server logs (`source=server`) or the per-request call log (`source=requests`). | | Infra health | `GET /v1/managed/infra-health` | Aggregated error clusters, tool errors, and latency percentiles over a time window. | | Feature states | `GET /v1/managed/features` | Which gated features are on / off / degraded on this instance, and why. | | Install apps / packs | `GET /v1/apps`, `POST /v1/apps/{name}/install` (`…/reload`, `…/uninstall`) | Marketplace app lifecycle — install a packaged vertical (agents + knowledge + UI) onto the instance. | > **Tip:** call `GET /v1/managed/deployment` first. It tells you which of the capabilities on this page a particular instance actually has enabled, so your integration can adapt instead of guessing. *** ## Where to go next * [**Install**](/libra-os/install.md) — stand up a self-hosted instance. * [**Documents & Knowledge**](/libra-os/documents-and-knowledge.md) — the most common end-to-end workflow. * [**Anthropic SDK Quickstart**](/libra-os/anthropic-sdk-quickstart.md) — use your existing Anthropic code against Libra OS. * [**Admin Guide**](/libra-os/admin-guide.md) — operate and troubleshoot a deployment. * [**Libra OS SDK**](https://github.com/libraos/sdk) — OpenAPI spec (source of truth), Python SDK, CLI, and worked partner examples.