> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The two API surfaces
> GreatBook has a DevCenter API that carries the money path and a backend GL read API over the book of record. What each is for, and when to use which.
# The two API surfaces
GreatBook exposes **two** HTTP APIs, and conflating them is the fastest way to build the wrong integration.
**What the product itself calls.**
The intake queue, both maker-checker gates, the Typewriter document surface, uploads, actions, payments, and the read endpoints the Books screens use.
This is the surface that carries the **money path**.
**The book of record, read-only.**
Journal entries, entry detail, the trial balance, the tie-out and a thin sub-ledger view, served straight off the canonical general ledger.
Use it when you want the ledger, not the workflow.
## Which one to use
| You want to | Surface | Route |
| -------------------------------------------- | ---------- | ------------------------------------------------------------- |
| list documents awaiting review | DevCenter | `GET /intake/queue` |
| approve a document, or approve its posting | DevCenter | `POST /intake/{id}/approve`, `POST /intake/{id}/post-approve` |
| compose, approve or download a document | DevCenter | `/typewriter/*` |
| render a P\&L, balance sheet or cash flow | DevCenter | `/stmt/*` |
| browse journal entries in the UI's own shape | DevCenter | `GET /gl/entries` |
| read the ledger as a system of record | backend GL | `GET /gl/entries`, `GET /gl/entries/{id}` |
| prove the book ties | backend GL | `GET /gl/trial-balance`, `GET /gl/reconciliation` |
Both surfaces have a router mounted at `/gl`, and they are **not** the same endpoints.
The DevCenter's `/gl/*` serves the Books screens and preserves a legacy response contract; the backend's `/gl/*` is the read API over the canonical ledger.
They run as different services on different ports, so check which base URL you are pointed at before matching a response shape.
## The shape of each
| | DevCenter API | Backend GL API |
| --------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| code | `langgraph_chat/devcenter/` | `backend/app/routers/external/gl.py` |
| routes | typed operations across the mounted DevCenter routers, including explicit slash aliases | 7 under `/gl` |
| driver | synchronous psycopg over the operational schema | async SQLAlchemy over the canonical GL |
| writes? | yes - this is the money path | one operational route, `POST /gl/sync-teable`; everything else reads |
| reached by | the UI's session-gated `/api/devcenter/*` proxy | the UI proxy, or a service token |
| response bodies | plain JSON objects | plain JSON objects |
Neither surface declares response models, so there is no generated schema worth rendering as an endpoint explorer.
These pages are written from the route handlers and their test suites instead, which is why each response below states the keys it actually returns rather than a type name.
## Endpoints by lane
| Lane | Page | Coverage |
| ---------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| the two gates - intake and posting | [Intake and the posting gate](/greatbook/api/intake) | review, approval, launch recovery and posting decisions |
| document composition and approval | [Typewriter documents](/greatbook/api/typewriter) | preview, immutable documents, approval and Clerk handoff |
| ledger, sub-ledgers, statements, reconciliation | [Ledger and statements](/greatbook/api/ledger) | canonical backend reads plus the web-facing operational projections |
| files, human tasks, agent runs and payment approvals | [Uploads, actions and payments](/greatbook/api/uploads-and-actions) | Timeline, Folders, human work, agent-run evidence and payment approval |
| the MCP product boundary | [The MCP interface](/greatbook/api/mcp) 🟡 Live ingress, current registry | Public metadata and the pinned source contract carry registry `1.14.1`; its live inventory contains 50 tools and 18 resources, while ChatGPT and Claude behavior remains unexercised. |
Plus the DevCenter's own service routes: `GET /ok`, `GET /connectors`, `POST /connectors/{id}/check`, `POST /connectors/check-all`, the deliberately inert QuickBooks OAuth redirect boundaries, and `POST /cache/invalidate`.
## Reviewed master maintenance
The DevCenter also mounts typed item and employee master-maintenance families under `/masters`.
Each family has native-record list, proposal list/detail, proposal creation, and exact approval routes.
Proposal creation and approval require a named human with `workflow.write`; reads accept `workflow.write` or `books.read`.
Approval reloads the stored proposal, binds its exact version and content hash, requires a different human, calls the existing item or employee writer, and appends the approval evidence in the same transaction.
This is not a generic table editor.
Item proposals accept identity, name, item type, and unit of measure only.
Employee proposals accept identity, name, and employee type only; pay, allocation, employment status, and effective-dated terms stay outside the contract.
The web routes are `/masters/items`, `/masters/items/proposals`, `/masters/employees`, and `/masters/employees/proposals`, with proposal-specific review pages beneath each family.
These routes and pages are verified in source; this documentation cut did not complete the workflow in production.
## Three rules that hold everywhere
**1.
Nothing is unauthenticated.**
Every route on both surfaces requires a verified identity.
On the DevCenter only `/ok`, the OpenAPI documents and the OAuth redirect boundaries are open.
Open callbacks are not an active connector: the current migration creates no OAuth client and activates no trusted binding.
**2.
The acting identity is derived, never supplied.**
A browser cannot choose who it is acting as.
That is not a hardening detail, it is the whole of the maker-checker control, because the actor string is what the `maker != checker` comparison is made against.
**3.
Reads are org-scoped by row-level security.**
A cross-org caller sees zero rows, enforced by the database rather than by a filter in application code.
All three are set out on [Auth, actors and org scoping](/greatbook/api/auth-and-tenancy).
## A first call
```bash theme={null}
# the DevCenter, as a service caller
curl -s "https:///intake/queue?status=pending" \
-H "Authorization: Bearer $WS_API_TOKEN" \
-H "X-Actor: ops@example.com" \
-H "X-WorthState-Org-Id: $ORG_ID"
```
```bash theme={null}
# the backend GL API
curl -s "https:///gl/trial-balance" \
-H "Authorization: Bearer $WS_API_TOKEN"
```
## Related
* [Auth, actors and org scoping](/greatbook/api/auth-and-tenancy) - the three ways to authenticate and the one way the actor is decided
* [Intake and the posting gate](/greatbook/api/intake) - the money path's two gates
* [The test-case reference](/greatbook/reference/test-cases) - every eval case, Close checksum family and GL invariant these surfaces are held to
* [The architecture](/greatbook/architecture) - where these services sit
* [What is live](/greatbook/status) - what is behind each of them today