For AI agents and crawlers: the canonical machine-readable documentation is at https://oomira.com/docs.txt (ontology directory at /docs.txt?doc=registry); the product overview is at https://oomira.com/llms.txt. The full text follows.

# Give an AI the context for its task

Oomira gives an AI relevant, structured context before it starts a task. The AI reads saved context when the user connected Oomira. Otherwise, it generates context from known facts and asks only for missing facts that affect the task.

## Choose the context source

| Available context | First action | Result |
| --- | --- | --- |
| Connected Oomira account | Call `whoami`, then read the relevant world | Current, sourced context |
| No saved context | Discover a schema, then call `scaffold` | Generated context and the next questions |
| Another person must answer | Create an interview session | Expiring browser or MCP interview |

Both paths return Oomira Context Format (OCF), a compact format an AI can use directly. The AI doesn't need to understand Oomira's storage model.

## Complete the task

1. Receive the user's task
2. Load saved context when available
3. Otherwise, discover a schema and generate context
4. Ask the next blocking question
5. Continue with the returned state and new answer
6. Complete the original task with the resulting OCF

Use research only when the task requires new evidence. Save the result only when later tasks should reuse it.

## The gaps are an acquisition plan, not a form

A generated context does not just list what a task needs — it says *how to get each piece*, so an agent gathers automatically and asks the person only for the irreducible set. The path nests into the same sections the subject is interviewed in (`<subject>.<section>.<record>.<field>`), every gap carries its acquisition route, and the context leads with a tally:

```
# 44 to fill — 33 on the public record · 1 possibly via search · 3 via a connected account · 7 to ask Acme Robotics · a plain ? = ask
acme_robotics.identity.legal_name_full: ? ← fetch [1]
acme_robotics.identity.batch_membership: ? ← search [2]
acme_robotics.identity.founded_date: ? ← fetch [3]
acme_robotics.identity.website: ? ← fetch [4]
acme_robotics.operations.headquarters_location: ? ← fetch [3]
acme_robotics.money.company_financials.annual_revenue: ? ← connect [5]

# sources
[1] corporate registry record
[2] public search
[3] opencorporates
[4] official home about or team page
[5] stripe
```

The source names are written once, in a numbered `# sources` legend at the end, and referenced inline — so a long source slug never repeats. A document gap reads `? ← upload`; which document proves a fact is an ontology property (`accepted_evidence`), derived at the schema level, not enumerated in the OCF.

| Route | Meaning | Agent action |
| --- | --- | --- |
| `← fetch <source>` | A public source that *has* this fact — a registry, API, or authored page (OpenCorporates, Wikidata, RDAP, the official site) | Retrieve directly — reliable, no permission |
| `← search <source>` | A public candidate that *might* surface it (a person's spouse or citizenship via biography/news) | Try it — a lead, not a guarantee |
| `← connect <system>` | The subject's own connected account (Stripe, Plaid, payroll, GitHub) | Pull over the user's OAuth connector |
| `← upload <doc>` | An issuer document (T4, pay record, cap table) | Read the document once provided |
| a bare `?` | Only the subject knows (a preference, a decision) | Ask the person — the minimal set |

The `fetch` vs `search` split is the source's declared yield — an authored fact mapping (`evidence_ceiling` verified/cited) versus a schema-driven candidate — so an agent knows what it will get versus what it can only try for. A bare `?` (no route) is the default: ask the subject. Read the routes top to bottom: fetch and connect first, search and ask last. That turns intake into orchestration — the same requirements engine an agent can call before it plans, so it knows exactly what it can gather versus what genuinely needs the human. The routes are declared per fact in the ontology; the OCF header documents the notation for any reader.

# Add context to an AI task

Choose one path based on whether the user connected Oomira.

## Read saved context

Connect `https://oomira.com/mcp` with OAuth. Call `whoami`, then call `about_me` or `about_world`. If the saved context is incomplete, call `list_schemas`, then `plan_interview`.

To collect missing facts from the subject, call `create_interview_session`. Ask its returned `questions` in the conversation, render its MCP App, or send its `interview_url`.

## Generate context without an account

First, discover the supported task schemas:

```bash
curl -s https://oomira.com/api/v1/schemas
```

Choose a returned `name`. The generator accepts schema names, not arbitrary task descriptions.

```bash
curl -sX POST https://oomira.com/api/v1/scaffold \
  -H 'content-type: application/json' \
  -d '{
    "profile": {
      "name": { "first": "Jane", "last": "Doe" },
      "residency": ["CA-ON"],
      "marital_status": "married"
    },
    "schema": "mortgage_application"
  }'
```

The response contains:

- `ocf`: usable context
- `targets`: every required fact and its state
- `questions`: the next planner actions
- `continuation`: the complete state for the next call
- `gaps`: a compatibility projection of `questions`

Ask the first blocking question in your own voice. Send `continuation` back as `continue_from` with only the new answer patch:

```bash
curl -sX POST https://oomira.com/api/v1/scaffold \
  -H 'content-type: application/json' \
  -d '{
    "continue_from": {
      "schema": "mortgage_application",
      "profile": {
        "name": { "first": "Jane", "last": "Doe" },
        "residency": ["CA-ON"],
        "marital_status": "married"
      },
      "answers": {}
    },
    "answers": { "property_target_value": 750000 }
  }'
```

Don't omit `continue_from`. The stateless API can't recover facts from an earlier request.

# Collect missing context with an interview

Use an interview session when an AI or application needs another person to supply missing facts. The session stores answers, then regenerates questions from the ontology planner after every answer. The API never stores a separate questionnaire.

## Choose keyless or authenticated storage

| Session | Create with | Default expiry | Sensitive facts |
| --- | --- | --- | --- |
| Keyless | No authorization header | 24 hours | Removed before storage and never returned |
| Authenticated | Bearer credential | 7 days | Available to the secure planner |

Both session types return an opaque bearer link. Treat `interview_url` like a password-reset link. The database stores only the token's SHA-256 hash.

An authenticated session persists answers inside the session. It does not silently write those answers into a durable world. Use an explicit world write or save action when later tasks should reuse them.

## Create a browser interview

This request creates a keyless session:

```bash
curl -sX POST https://oomira.com/api/v1/interview-sessions \
  -H 'content-type: application/json' \
  -d '{
    "situation": "mortgage_application",
    "profile": { "name": { "first": "Jane", "last": "Doe" }, "residency": ["CA-ON"] },
    "answers": {}
  }'
```

The response includes:

- `interview_url`: browser handoff at `/i/{token}`
- `app.resource_uri`: Model Context Protocol (MCP) App resource for supporting hosts
- `questions`: current ontology-planned actions
- `targets`: every required fact and its current state
- `ocf`: current Oomira Context Format (OCF)
- `session.answers`: accumulated typed answers

## Submit typed answers and re-plan

Read each question's `writes[].input` and `shape`. Send values under those input keys. Preserve booleans, arrays, numbers, and objects as JSON values.

```bash
curl -sX PATCH \
  https://oomira.com/api/v1/interview-sessions/oom_iv_your_token_here/answers \
  -H 'content-type: application/json' \
  -d '{
    "answers": {
      "gross_annual_income": 125000,
      "income_type": "salary",
      "co_borrower": false
    }
  }'
```

The response contains the merged answers and the new `questions` array. Known, inferred, inapplicable, and explicitly absent facts disappear from the remaining interview automatically.

## Ask questions through MCP

Connect `https://oomira.com/mcp` with OAuth, then:

1. Call `list_schemas`
2. Call `create_interview_session` with a returned schema name
3. Ask the first blocking question from `questions`
4. Call `submit_interview_answers` with the user's typed answer
5. Repeat until no blocking question remains

An MCP host can render `ui://oomira/interview/{token}` when it supports MCP Apps. Otherwise, the AI can ask questions in the conversation or present `interview_url`.

## Read or revoke a session

Call `GET /api/v1/interview-sessions/{token}` to retrieve current state. Call `DELETE /api/v1/interview-sessions/{token}` to revoke the bearer link immediately.

The concise machine contract is also available at `/interviews.txt`.

# Use saved context

Saved context prevents an AI from asking for facts the user already supplied. A world stores typed facts, dates, sources, relationships, and history for a person, company, or project.

## Personal and company worlds

A founder's personal world and company world remain separate records. The founder relationship bridges them, so a task can use the relevant facts without copying private personal context into the company. Create or select the task's world first; use cross-world context only when the caller is authorized for both.

## Use MCP from an AI client

Connect `https://oomira.com/mcp` with OAuth, then:

1. Call `whoami`
2. Select the relevant world
3. Call `about_me` or `about_world`
4. Use narrower tools only when the task needs more detail

## Use HTTP from an application

Call `GET /api/v1/worlds/:id/ocf` with an `oom_live_` bearer key when your application already knows the world.

Generated context is stateless. Persist it only when another task should reuse it.

# Read Oomira Context Format

Oomira Context Format (OCF) is the compact output shared by saved and generated context.

```text
you.identity.legal_name: Jane Doe [stated: user]
you.work.employment.compensation: 185000 CAD [doc ✓] @2026-07-13
you.identity.industry: robotics [stated: agent]
you.living.citizenship: present [inferred: existence]
you.people.spouse: ?
you.assets.real_estate: ? ← connect plaid
```

| Part | Meaning |
| --- | --- |
| `subject.section.field` | The path nests: subject, its life section, then the typed fact (a record adds a segment, `you.work.employment.compensation`) |
| Value | Resolved value; `present` = exists but not captured yet; `none` = confirmed absent |
| `[tier]` | WHO asserted it + how — `[stated: user]` (a human), `[stated: agent]` (an AI, verify it), `[doc ✓]`, `[sourced ✓]`, `[cited]`, `[rule]`, `[inferred: …]` |
| `@date` | Effective / as-of date |
| `?` / `? ← route` | A gap and how to fill it — a bare `?` = ask the subject |

OCF is a task projection, not a database export. It preserves the details that can change an AI's reasoning: type, date, evidence, currency, explicit absence, and unresolved facts.

# Find fields in the ontology

The ontology defines every entity, fact, value shape, evidence rule, and temporal rule that Oomira can represent. Generated context, saved worlds, OCF, and the API share this contract.

A schema is a named subset of the ontology for one task. The planner compares that schema with known facts and returns only the questions that can advance the task.

Search the registry below when you need an exact field, value shape, or evidence rule.

# Create a schema from a representative source

Use this workflow when a form, directory, checklist, or document already expresses the context your task needs. Oomira extracts its reusable field contract, maps each requirement to the ontology, and leaves the draft editable. Extraction never saves facts or starts enrichment.

1. Call `POST /api/v1/schemas/preview` with `url` or `source_text`
2. Review `requirements`, remove unwanted fields, and map every item in `unmapped`
3. Call `POST /api/v1/schemas` with the approved `fields`
4. Apply the saved schema to a world, then enrich its missing facts

`POST /api/v1/schemas/preview` uses AI when it reads a link. The response reports `writes: false`. A source label is not an ontology fact until the response includes a `fact_type` and you approve it.

```typescript
const draft = await oomira.post('/api/v1/schemas/preview', {
  url: 'https://example.com/representative-application',
  entity_type: 'company',
})

await oomira.post('/api/v1/schemas', {
  name: 'accelerator_application',
  display_name: 'Accelerator application',
  entity_type: 'company',
  fields: draft.fields.map((field) => field.fact_type),
})
```

The same flow appears in `/demo` under **Generate from a source**. Paste a link, edit the required facts, then select **Save schema**.

# Choose an API endpoint

Use the smallest surface that matches the task. Ontology discovery, built-in schema discovery, stateless context generation, and pricing are public.

## Context

| Method | Endpoint | Use | Auth |
| --- | --- | --- | --- |
| GET | `/api/v1/schemas` | Discover supported task schemas | None |
| POST | `/api/v1/scaffold` | Generate OCF and planner questions | None |
| POST | `/api/v1/interview-sessions` | Create an expiring interview handoff | Optional key |
| GET, DELETE | `/api/v1/interview-sessions/:token` | Read or revoke an interview | Bearer link |
| POST, PATCH | `/api/v1/interview-sessions/:token/answers` | Save answers and re-plan questions | Bearer link |
| GET | `/api/v1/worlds/:id/ocf` | Read saved context | Key |
| POST | `/api/v1/research` | Discover or verify facts | Key |
| POST | `/api/v1/sources/preview` | Preview one URL or named provider | Key |
| POST | `/api/v1/sources/commit` | Save approved preview facts | Key |

## Ontology and schemas

| Method | Endpoint | Use | Auth |
| --- | --- | --- | --- |
| GET | `/api/v1/ontology` | List types, evidence rules, source coverage, and completion routes | None |
| GET | `/api/v1/schemas/:name` | Read a built-in or custom schema | Built-in: none; custom: key |
| POST | `/api/v1/schemas/preview` | Compile a representative URL or document into an editable schema draft | Key |
| POST | `/api/v1/schemas` | Save a custom schema | Key |
| POST | `/api/v1/worlds/:id/apply-schema` | Apply a schema to a world | Key |

## Saved worlds

| Method | Endpoint | Use | Auth |
| --- | --- | --- | --- |
| GET, POST | `/api/v1/worlds` | List or create worlds | Key |
| GET | `/api/v1/worlds/:id` | Read a world | Key |
| GET, POST | `/api/v1/worlds/:id/entities` | Read or write facts | Key |
| GET | `/api/v1/worlds/:id/graph` | Read relationships | Key |
| GET | `/api/v1/worlds/:id/timeline` | Read dated changes | Key |

## Extraction, files, and export

| Method | Endpoint | Use | Auth |
| --- | --- | --- | --- |
| POST | `/api/v1/structure` | Extract typed facts from supplied content | Key |
| POST | `/api/v1/orient` | Resolve a seed to an entity and source plan | Key |
| GET | `/api/v1/integrations/:provider` | Inspect a connected provider | Key |
| GET | `/api/v1/files/list`, `/read`, `/glob` | Discover and read world files | Key |
| POST | `/api/v1/files/write`, `/edit`, `/grep` | Write, patch, or search world files | Key |
| POST | `/api/v1/takeout/generate` | Build a sourced world export | Key |
| GET | `/api/v1/takeout/download` | Download the generated export | Key |

Send `Authorization: Bearer oom_live_your_access_token_here` to endpoints marked **Key**. Creating an interview session accepts optional authentication: without a key it creates a restricted keyless session. Reading, answering, and revoking a session use the opaque token in the session URL. API keys are server-side secrets.

# Connect an AI with MCP

The Model Context Protocol (MCP) gives an AI direct access to saved Oomira context and ontology-planned interview sessions.

Connect `https://oomira.com/mcp` with OAuth. Call `whoami` first. Then call `about_me` for cross-world context or `about_world` for one world. Prefer saved facts over public or model-generated guesses. If a required fact is missing, call `list_schemas`, then plan or create an interview.

The world graph remains read-only through MCP. `create_interview_session` and `submit_interview_answers` write only to an isolated, expiring session. They never silently change durable world facts.

## Available tools

| Tool | Inputs | Description |
| --- | --- | --- |
| `list_schemas` | — | List built-in and custom schemas that define the facts a task can require. |
| `plan_interview` | `situation, answers?, stage?, subject?` | Plan the next questions for a task from the facts already known. Re-call with answers to shrink the gaps. |
| `create_interview_session` | `situation, world_id?, profile?, answers?, subject?` | Create an authenticated interview with structured questions, an MCP App resource, and a browser link. |
| `submit_interview_answers` | `token, answers, complete?` | Save a typed answer patch in an interview session and return the re-planned remaining questions. |
| `whoami` | — | Who you are, your businesses, and the worlds you own. Nothing about a world’s contents. |
| `about_me` | `compact?` | You across all your worlds: a cross-world projection of the owner (the “self” entity everywhere it appears). |
| `about_world` | `world?, compact?` | Deep orient on one world: its lead/self entity, facts, neighborhood, timeline, and files. |
| `get_entity` | `query, world?, include?, expand?` | Fetch an entity by slug or name. Pass "self" for the workspace owner. include=minimal|facts|full trades detail for size. |
| `search_facts` | `query, world?` | Keyword search across entity names and fact values — the “what do you know about X” tool. Searches a world’s materialized entity records, so a world not yet materialized (e.g. a frozen snapshot) returns nothing. |
| `get_ontology` | `world?, entity_type?` | What this world tracks: its per-world entity + fact types and metadata (the schema, not the data). |
| `get_graph` | `world?, include_superseded?` | The whole entity-relationship graph: entities + edges, in one call. Inverse edges are derived, never stored twice. |
| `get_timeline` | `world?, category?, from?, to?, limit?` | The world’s history as a dated event stream, with provenance behind each event. |
| `list_directory` | `path?, recursive?, max_depth?` | List files in a world, like `ls`. Each world has a writable file tree and Scout’s read-only derived graph. |
| `read_file` | `path, offset?, limit?` | Read a file, like `cat` / `sed -n`. Large files auto-slice; page with offset/limit. |
| `glob` | `pattern` | Find files by glob pattern, like `find`. A world-slug prefix scopes to one world; without it, fans out across all. |
| `grep` | `pattern, path?, glob?, case_insensitive?` | Regex search of file contents, like `grep -rn`. Returns path + line number to feed straight into read_file. |

Use `create_interview_session` when the AI should ask questions in the conversation, display an MCP App, or provide a browser handoff. Write durable facts through the HTTP worlds API.

# Understand pricing

Reading and generating context is free. Verification and persistent hosting are paid.

| Activity | Price model |
| --- | --- |
| Read context, call `scaffold`, or use `@oomira/world` | Free |
| Search providers or run models for research | Provider cost plus the displayed markup |
| Keep a persistent, maintained world | Monthly plan |

The interactive table below reads the same pricing store used by billing. Applications can read those rows from public `GET /api/v1/pricing`. This text doesn't copy rates, so it can't drift from billing.

An AI accesses enrichment through one Oomira API, but upstream execution varies. Oomira uses its provider account for services such as Brave, Exa, Perplexity, OpenCorporates, X, Reddit, and Anthropic. It reads Wikidata, Wikipedia, RDAP, public GitHub data, websites, RSS, Atom, Substack, YouTube feeds, Medium feeds, and Wayback through direct public endpoints. Connected GitHub, Google, Dropbox, Stripe, and Plaid data requires user authorization. No source runs automatically. Provider-backed research, models, and image generation are charged only when invoked.