Company Brain API

Policy-scoped retrieval, grounded answers, and website ingestion over your organization's shared knowledge — one bearer-authenticated HTTP contract, molecule.v1.

Molecule OS is the shared company brain: a single retrieval + policy + evals plane that every product (JustCall, Helpwise, ServiceAgent) queries instead of each building its own RAG stack. This is the reference for Boundary 1 — the HTTP API a product or an assistant calls to ask the brain a question.

Every request carries a bearer API key that is a principal: it resolves to a (tenant, product) and the surfaces it may act on. The caller never supplies scope — the audience (end_customer vs internal_agent) is derived from the key. That single rule is what keeps a public website visitor and an internal agent asking the same query and getting correctly different answers.

Get started

Quickstart

Boot the brain with Docker, seed a tenant, and make your first call in under five minutes.

Authentication

How API keys map to principals, surfaces, and audiences.

Core concepts

Classification, ACL tokens, the public/private bifurcation, and snapshots.

TypeScript SDK

@molecule/sdk — the typed client. Retrieve, stream answers, and feedback from any repo.

Endpoints

The full molecule.v1 surface: retrieve, answer, ingest, policy, sources.

The endpoints

POST /v1/retrieve

Policy-scoped hybrid retrieval → ranked, scored chunks.

POST /v1/answer

Retrieval + grounded generation with citations.

POST /v1/answer/stream

The same grounded answer, streamed token-by-token over SSE.

POST /v1/feedback

Thumbs up/down on an answer, keyed by decisionId — the eval-flywheel signal.

POST /v1/policy/resolve

Explain the compiled scope for a surface — the ACL tokens a key holds.

POST /v1/sources/website

Ingest a whole website from a URL — crawl → extract → chunk → embed.

POST /v1/ingest

Seed documents directly, bypassing the crawler.

GET /v1/snapshots

Snapshot stamps — reproducible, point-in-time reads.

Base URL

All endpoints are served under a single origin. Locally that is the gateway container:

http://localhost:8080

Contract source of truth

The request and response shapes in this reference are generated from the same Zod schemas the gateway validates against (@molecule/core, molecule.v1). If a field is documented here, it exists in the contract — the docs can't drift from the API.

What this is not

The brain is deliberately two boundaries, not one. This reference covers Boundary 1 (ask the brain). The ingestion plane (connectors → raw append-only log → derivation) and the eval plane (datasets, experiments, scorers) are separate workstreams; the dashboard is where evals live.