Extract with AI Schemas

What it does

An AI Schema is the list of fields fileAI fills for a kind of document, such as an invoice’s Invoice number, Total amount and Line items table. fileAI classifies each file into a file type and fills that type’s schema, so every invoice in your project comes back with the same fields in the same shape. See Concepts for how file types, files and documents relate.

When to use it

You receive the same kinds of documents again and again (invoices, bank statements, contracts) and need the same fields from each, such as a contract’s parties and dates.
You need to read extracted values into your own system, and correct a wrong value or table cell over the API.
You already know what a file is and want to skip classification by passing its file type’s blueprintId on upload.

How it works

Upload

Send the file through Uploads.

Classify

fileAI classifies the file. If it matches a file type you already have, fileAI fills that type’s current schema. If it matches nothing, fileAI proposes a new file type with a generated schema (zero-shot: no template or training data needed).

Approve new types

You review and approve new types (Verify in the app) or call PATCH /v1/file-type/approve.

Read the values

GET /v1/files/{fileId}/values returns the filled fields, grouped by schema.

To stop fileAI from proposing new types, use schema locking. To skip classification and force a file type for an upload, pass its blueprintId when you request the upload (Uploads).

Try it

Read the values extracted from a file. Use a fileId from the files[] of GET /v1/uploads/{uploadId}.

curl "$FILEAI_BASE_URL/files/<fileId>/values" \
  -H "x-api-key: $FILEAI_API_KEY"

import os, requests

BASE = "https://api.orion.file.ai/prod/v1"
HEADERS = {"x-api-key": os.environ["FILEAI_API_KEY"]}

values = requests.get(f"{BASE}/files/{file_id}/values", headers=HEADERS).json()
for form in values["formValues"]:
    print(form["schemaName"], [(f["title"], f["value"]) for f in form["fields"]])

const BASE = "https://api.orion.file.ai/prod/v1";
const headers = { "x-api-key": process.env.FILEAI_API_KEY };

const values = await fetch(`${BASE}/files/${fileId}/values`, { headers }).then((r) => r.json());
for (const form of values.formValues) console.log(form.schemaName, form.fields.map((f) => [f.title, f.value]));

Understand the result

Response (200)

{
  "formValues": [
    {
      "id": "67ea5f20650d2fb5e33c1ffb",
      "fileId": "7870a865-d560-4183-82c1-4b10e696e930_2",
      "schemaName": "Education Certificate",
      "fields": [
        {
          "title": "Degree",
          "type": "string",
          "description": "The degree obtained by the individual",
          "value": "Bachelor of Mathematics"
        }
      ]
    }
  ],
  "count": 1,
  "currentPage": 1
}

Field	Meaning
`formValues[]`	The file’s extracted values, one entry per schema.
`formValues[].id`	The form value id. Send it as `schemaValueId` to correct a value.
`formValues[].schemaName`	The schema the values were filled from.
`fields[]`	Each field’s `title`, `type`, `description` and `value`. A number or table cell whose value is `0` comes back as `null`. See Data types.
`count`, `currentPage`	Pagination of `formValues`.

For tables with more than 100 rows, pass includeFullTableData=true to get every row. Citations are an app feature and are not in the documented response. See Citations and validations.

Next steps

Schema locking

Keep files inside the file types you have approved.

Data types

Field types, formats and how values come back.

Extraction prompts

Write field descriptions that extract reliably.

File Intelligence

Project-wide processing settings and the schema list.

Reference

File types and schemas

A file type (API: blueprint, blueprintId) is a kind of document, such as Invoice. Its schema (schemaId) holds the field definitions. Schemas are versioned: editing one creates a new version, and the file type points at its current version. Concepts defines both terms.

Where field values come from

Source	How a field gets its value
Single file	Extracted from the document itself. This is the default for every field.
Cross-file	Looked up from another document in your project, through a cross-file reference on the field.
Online data	Enriched from the web when the field has `internet_context` set to `true`.

Edit a schema in the app

Open a processed file

Open the file and select the AI Schema tab to see the extracted fields.

Adjust fields

Edit a field directly, or click the sparkle icon next to it, describe how the field should be captured, then click Run and Save. Mark fields thumbs up or thumbs down to flag correct and incorrect values.

Edit the saved schema

Go to File Intelligence → Extraction Schema and select the schema. Add a table or field, remove one with the trash icon, hide one with the eye icon, or edit one with the pencil icon. Click Save AI schema.

Schema edits are versioned. They apply to newly processed files; existing files keep the version they were processed with until you re-run them with PATCH /v1/files/schema/rerun.

For writing good field descriptions, see Extraction prompts. For field types, see Data types.

Correct a value

To correct a value, send the form value id as schemaValueId:

curl -X PATCH "$FILEAI_BASE_URL/files/<fileId>/values" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaValueId": "67ea5f20650d2fb5e33c1ffb",
    "fieldPaths": [
      { "path": "/Supplier country", "value": "Netherlands" },
      { "path": "Line_items", "cells": [{ "rowIndex": 0, "column": "gl_code", "value": "1234" }] }
    ]
  }'

Each fieldPaths entry sets exactly one of value (a scalar field, addressed by its title) or cells (table cells, addressed by zero-based rowIndex and column title).

File type endpoints

Endpoint	What it does
`GET /v1/file-type`	List file types, each with its `currentSchemaVersion` and `usageApprovalState`.
`PATCH /v1/file-type/approve`	Approve a file type (Verify in the app). Body: `blueprintId` and `schemaId`, both required.
`PATCH /v1/file-type/rename`	Rename a file type. Body: `blueprintId` and `name`, both required.
`DELETE /v1/file-type`	Delete file types. Body: `blueprintIds`, 1 to 50 ids.

DELETE /v1/file-type returns 200 whenever the request is valid, with deletedCount, failedCount and per-id errors. More than 50 ids is a 422 VALIDATION_FAILED, and nothing is deleted. Duplicate ids are processed once, and an id that is already deleted reports Schema is not found or already deleted, so retries are safe.

Deleting a file type is permanent. There is no API to restore it.

Schema endpoints

Endpoint	What it does
`GET /v1/schemas`	List schemas. Filter with `schemaIds` or `uploadIds`.
`GET /v1/schemas/file-type`	List the schemas of one file type. `blueprintId` is required.
`PATCH /v1/files/schema`	Add, update or delete field definitions on a file’s schema, creating a new schema version.
`POST /v1/files/schema/export`	Export schemas to a ZIP. Body: `aiSchemaIds`, a comma-separated string. Returns `exportedFileDownloadUrl`, valid for 1 hour.
`POST /v1/files/schema/import`	Import an exported ZIP, sent as `multipart/form-data` in the `file` field. Ignores `Idempotency-Key`. Imported file types and schemas get new ids. The import fails if a file type with the same class name already exists.

Each schema carries blueprintId, schemaType (SYSTEM, CUSTOM or AI), state and usageApprovalState. All list endpoints support pagination, including cursor mode. PATCH /v1/schemas is deprecated. To change values, use PATCH /v1/files/{fileId}/values.

Values

Endpoint	What it does
`GET /v1/files/{fileId}/values`	Read a file’s extracted values, grouped by schema. For tables with more than 100 rows, pass `includeFullTableData=true` to get every row.
`PATCH /v1/files/{fileId}/values`	Correct scalar values and table cells. Returns `{ "success": true }`.
`PATCH /v1/files/schema/rerun`	Re-fill a file against its current schema version. Body: `fileId` (required), `backgroundRerun`, and `rerunOptions` (`paths`, `partialRerun`, `notification`).

JSON write endpoints accept an optional Idempotency-Key header; POST /v1/files/schema/import ignores it. See Idempotency.

Get started

Products

Build

Go live

Extract with AI Schemas

What it does

When to use it

How it works

Try it

Understand the result

Next steps

Schema locking

Data types

Extraction prompts

File Intelligence

Reference

File types and schemas

Where field values come from

Edit a schema in the app

Correct a value

File type endpoints

Schema endpoints

Values

​What it does

​When to use it

​How it works

​Try it

​Understand the result

​Next steps

Schema locking

Data types

Extraction prompts

File Intelligence

​Reference

​File types and schemas

​Where field values come from

​Edit a schema in the app

​Correct a value

​File type endpoints

​Schema endpoints

​Values

What it does

When to use it

How it works

Try it

Understand the result

Next steps

Reference

File types and schemas

Where field values come from

Edit a schema in the app

Correct a value

File type endpoints

Schema endpoints

Values