# Extract with AI Schemas
Source: https://docs.file.ai/extract/ai-schemas

> Define the fields fileAI extracts from each kind of document, then read and correct the values over the API.

fileScout

# Extract with AI Schemas

Copy pageCopy page

Define the fields fileAI extracts from each kind of document, then read and correct the values over the API.

Copy pageCopy page

## 

[​

](#what-it-does)

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](/concepts) for how file types, files and documents relate.

## 

[​

](#when-to-use-it)

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)

How it works

1

Upload

Send the file through [Uploads](/ingest/uploads).

2

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).

3

Approve new types

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

4

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](/extract/schema-locking). To skip classification and force a file type for an upload, pass its `blueprintId` when you request the upload ([Uploads](/ingest/uploads)).

## 

[​

](#try-it)

Try it

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

cURL

Python

Node.js

```
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)

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](#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](/extract/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](/verify/citations-validations).

## 

[​

](#next-steps)

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)

Reference

### 

[​

](#file-types-and-schemas)

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](/concepts) defines both terms.

### 

[​

](#where-field-values-come-from)

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)

Edit a schema in the app

1

Open a processed file

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

2

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.

3

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](/extract/extraction-prompts). For field types, see [Data types](/extract/data-types).

### 

[​

](#correct-a-value)

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)

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)

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](/api/pagination), including cursor mode. `PATCH /v1/schemas` is deprecated. To change values, use `PATCH /v1/files/{fileId}/values`.

### 

[​

](#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](/api/idempotency).

[Previous](/ingest/ocr-models)[

Split & classify

Send one document, get back extracted values, split boundaries or a document type as an async job.

Next

](/extract/split-classify)

⌘I

## On this page

*   [What it does](#what-it-does)
*   [When to use it](#when-to-use-it)
*   [How it works](#how-it-works)
*   [Try it](#try-it)
*   [Understand the result](#understand-the-result)
*   [Next steps](#next-steps)
*   [Reference](#reference)
    *   [File types and schemas](#file-types-and-schemas)
    *   [Where field values come from](#where-field-values-come-from)
    *   [Edit a schema in the app](#edit-a-schema-in-the-app)
    *   [Correct a value](#correct-a-value)
    *   [File type endpoints](#file-type-endpoints)
    *   [Schema endpoints](#schema-endpoints)
    *   [Values](#values)