# AI Inside API

> AI Inside by FabricAI is a REST API for purchase-invoice automation. You send it
> invoices and it returns predictions for every invoice row — accounts, and dimensions
> (which is also how VAT handling, cost centres and approval routing are modelled). You
> feed finalized invoices back as training data and retrain periodically to improve
> accuracy.

Read these six notes before writing any client code.

- **The API is unversioned.** Every endpoint sits at the host root, e.g.
  `https://ai.fabricai.io/clients/{clientId}/invoices`. Do not add a version prefix —
  `/v1/...` and `/v2/...` are not routes. `GET /` reports a build string like
  `v2.46.1-dirty`; that is the software build, not a URL prefix and not a contract version.
- **Fetch and parse the sources; do not summarize them.** `getting-started.md` is ~42 KB and
  the specification is ~292 KB. Reading either through a summarizer drops the field names,
  and this API punishes invented field names. Query the specification with a tool — it holds
  enums, required fields and response codes that appear in no guide.
- **Nothing predicts until a model is `DEPLOYED`.** `POST /clients/{clientId}/invoices`
  returns **400** unless that client already has a model with `label: ACCOUNT` and status
  `DEPLOYED` — not `COMPLETED`, and a sibling client's model does not count. Build and
  verify the training half of your integration first. There is no enforced minimum training
  volume, so you can start before a backfill completes; the published 50–100 invoices is an
  accuracy floor, not a gate. Note also that once a processor is deprecated and more than 6
  months past its `plannedEndOfLife`, every `DEPLOYED` model using it is automatically
  deleted, which re-triggers this same 400 months later — there is no changelog or
  deprecation feed, so alarm on `plannedEndOfLife` yourself.
- **There is no `VAT` prediction label.** The model `label` enum is exactly `ACCOUNT` and
  `DIMENSION`. Everything predictable that is not an account is a **dimension** — VAT
  handling, cost centre, department, approver. So VAT predictions mean defining a dimension
  whose items are your VAT status codes and training a `DIMENSION` model for it. Expect
  several models per client.
- **The invoice `id` is supplied by you and is the primary key.** Reposting an id whose
  invoice is already `COMPLETED` fails with **409 Conflict**; any other status is
  **overwritten in place**, including mid-prediction. Neither is a retry path — suffix the
  id per workflow stage (`1234_approval`, `1234_validation`) from day one, because
  retrofitting it is a data migration.
- **Credentials are issued by FabricAI and are not self-service.** Development and
  production credentials are separate; request both. See Authentication, then get in touch:
  https://fabricai.fi/ota-yhteytta/

Environments: production `https://ai.fabricai.io`, development `https://ai.dev.fabricai.io`
(route-identical, so it is a safe build target).

## Start here

- [Live route inventory](https://ai.fabricai.io/routes): the deployed routes, public and unauthenticated. The cheapest orientation available and it tells you what you can skip. Treat it as ground truth, noting it omits `/routes` itself and `/metrics`
- [Getting started](https://ai.fabricai.io/static/guides/getting-started.md): the complete walkthrough from first request to live predictions, with real request and response bodies. Read this one in full — the rest is reference
- [OpenAPI specification](https://ai.fabricai.io/swagger/doc.json): Swagger 2.0, generated from the running code. Authoritative for enums, required fields and response codes. For an OpenAPI 3.x generator: `npx swagger2openapi swagger2.json -o openapi3.json`
- [Invoice formats and training data](https://ai.fabricai.io/static/guides/invoice-data.md): the canonical field reference — the JSON invoice schema and its required fields, `invoiceTargets`, and the row-mapping rule (`id` for JSON invoices, `index` for XML). You will need this to write the mapping layer, which is where integrations spend most of their debugging time
- [API responses and errors](https://ai.fabricai.io/static/guides/api-responses.md): the `data`/`count` envelope, the `error` field, status codes (note `202` for posting an invoice), pagination (`page`/`limit`, max 50; `continuationToken` for training invoices, max 1000) and filtering syntax. You cannot parse a single response without this
- [Authentication](https://ai.fabricai.io/static/guides/authentication.md): provider keys, organization keys, `R`/`RW` scopes and JWT exchange. Where the prose and the permission **table** disagree, the table is authoritative

## Reference

- [Processors and models](https://ai.fabricai.io/static/guides/processors.md): choosing a processor, and the model lifecycle `PENDING → PRE_PROCESSING → RUNNING → COMPLETED → DEPLOYED`. Read processor ids from `/processors` at runtime rather than hard-coding them; `COMPLETED → DEPLOYED` is automatic with no deploy endpoint
- [Organization structure](https://ai.fabricai.io/static/guides/organization-structure.md): mapping accounting offices and in-house customers onto organizations and clients. One organization per accounting office gives you per-customer billing separation and read-only analytics keys. Awkward to change later, and the guide is brief — ask us if your topology is not obvious
- [Introduction](https://ai.fabricai.io/static/guides/developer_guide.md): what AI Inside is and the Provider → Organization → Client hierarchy. Concepts only, no endpoints
- [DICE developer guide](https://ai.fabricai.io/static/guides/dice_guide.md): document interpretation (OCR and structuring) for invoices arriving as PDFs or images. DICE requires a **provider** key with the `dice` permission — organization keys cannot call it

## Also worth knowing

- **Payload precedence.** An invoice may be sent as JSON (`invoice`), base64 XML (`xml` plus `schema`, using `finvoice` or `peppol`), or `ocr`. Send exactly one: if you send `invoice` (JSON), that is what is used and both `xml` and `ocr` are ignored — and an ignored `xml` is discarded, not turned into an attachment, so add the original to the JSON invoice's own `attachments` array if you want to keep it. `smartscan`/`ocr` has no documented shape — ask us if you need OCR intake.
- **Two features are live but thinly documented**, and both may change your design, so ask us before building around them: **client automations** ("Progressive Automation" — server-side confidence-based automation, possibly replacing gating logic you were about to write) and the **client rules engine** (deterministic overrides on top of predictions; its schema endpoint requires a key).
- **The one invariant the API enforces** on an invoice is that `total` equals the sum of row `value`s within a small tolerance; a mismatch is a 400. The consistency of `accountingValue` and `vatPercent` on training targets is a model-quality recommendation, not a validation.

## Optional

- [All guides concatenated](https://ai.fabricai.io/llms-full.txt): every guide above in one file, for loading the full documentation set in a single request
- [Sample training invoice](https://ai.fabricai.io/static/sample_invoice_1.json) and [a second example](https://ai.fabricai.io/static/sample_invoice_2.json): note these are **training** invoices — they carry `invoiceTargets` — not prediction payloads
- [Human-browsable documentation](https://ai.fabricai.io/docs): a JavaScript application that renders the guides listed above. Use the raw markdown and the specification instead