# Basis

> Take an xlsx. Get back the computation, the references, the media, and a certificate of trust — in a shape your language model can act on directly.

Basis parses .xlsx/.xlsm workbooks and streams back newline-delimited JSON:
a typed cell graph, a formula dependency edge list, cell-anchored embedded
images, and an audit trail that verifies every formula against Excel's own
cached values. No bounding-box OCR, no screenshots — structured records.

Two HTTP entry points, both bearer-authenticated: `QUERY /api/v1/stream`
(blocks until done, always returns NDJSON — safe/idempotent, so QUERY per
RFC 10008 is the native fit; `POST /api/v1/stream` still works identically
as a deprecated fallback) and `POST /v1/jobs` (adaptively inline or async —
poll `GET /v1/jobs/{id}` or fetch the result from `GET /v1/jobs/{id}/stream`,
with webhook notification on completion; large multi-sheet workbooks can
also be fetched one sheet at a time via `GET /v1/jobs/{id}/sheets`).

If your agent speaks MCP (Claude Code, Cursor, Claude Desktop), the
`basis-mcp` stdio server wraps this same API as tools: `parse_workbook`,
`submit_job`, `get_job_status`, `stream_job` — the most direct integration
path, no HTTP client code required.

## Start here

- [Full documentation](/docs) — human-readable reference: auth, record
  schemas, jobs, limits, errors, worked examples.
- [llms-full.txt](/llms-full.txt) — the same documentation as plain text,
  generated from the same source, for pasting into a context window.
- [openapi.yaml](/openapi.yaml) — OpenAPI 3.2 spec: every path, status
  code, and schema, machine-readable.

## Integrate

- MCP server (`basis-mcp`) — stdio server exposing `parse_workbook`,
  `submit_job`, `get_job_status`, `stream_job` as tools. Contact your
  account rep for setup docs.
- SDK (`@basis/parse`) — TypeScript client (`Basis` class:
  `parse()`/`submitJob()`/`getJob()`/`streamJob()`). Source-only for now,
  not yet published to npm — contact your account rep for access.
- Raw HTTP — `curl -X QUERY /api/v1/stream --data-binary @workbook.xlsx
  -H "Authorization: Bearer $TOKEN"` (`-X POST` still works, deprecated).
  See [/docs#quickstart](/docs#quickstart).

## Reference

- [Record types](/docs#records) — `workbook_meta`, `sheet`, `cell`,
  `edge`, `image`, `image_summary`, `audit` (7 NDJSON record shapes).
- [Errors](/docs#errors) — status codes and `{error: {code, message}}` shapes.
- [Jobs & webhooks](/docs#jobs) — async job lifecycle, `?mode=`,
  `?webhook_url=`, HMAC signing.
- [Sheets](/docs#jobs-sheets) — fetch/resume one sheet's NDJSON at a time
  instead of buffering the whole job stream.
- [Auth](/docs#auth) — bearer token, per-workspace.
- [Limits](/docs#limits) — max upload size, image inlining threshold.

## Optional

- [What you can build](/docs#build) — lineage graphs, vision-model
  cross-checks, workbook diffing, ETL without formula re-derivation.
- [Not included](/docs#not-included) — explicit scope boundaries.
- [Versioning](/docs#versioning) — `x-basis-api-version` header policy.