> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a file's extracted values (fields and table/list cells)
> Update document form values for a file, for both scalar fields and table/list cells.
The `schemaValueId` field is the `id` returned by `GET /files/:fileId/values` (the form value id).
The `fieldPaths` field is an array of updates. Each entry must specify **exactly one** of:
- `value`: the new value for a scalar field. The `path` is the field title (the leading slash is optional, e.g. `/Supplier country`).
- `cells`: cell-level updates for a table/list field. The `path` is the table field title (e.g. `Line_items`). Each cell contains:
- `rowIndex`: the zero-based row index within the table.
- `column`: the column title (must match one of the table columns).
- `value`: the new cell value.
Table updates are a full read-modify-write: the complete CSV-backed rows are loaded, the specified cells are applied, and the table is re-persisted (updating the preview, document history, audit trail, and re-flattening the document).
Update the extracted values of a file — both scalar fields and individual
table/list cells.
This endpoint replaces the value-updating use of
[`PATCH /schemas`](/api-reference/endpoint/patch-a-schema), which is now
deprecated for that purpose. Use `PATCH /schemas` only to change schema field
*definitions*.
## Request Parameters
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------- |
| fileId | string | Yes | The ID of the file to update |
### Request Body
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| schemaValueId | string | Yes | The form value id — the `id` returned by [`GET /files/{fileId}/values`](/api-reference/endpoint/get-file-schema-values-by-fileids) |
| fieldPaths | array | Yes | The updates to apply. See below. |
#### fieldPaths entries
Each entry must specify **exactly one** of `value` or `cells`.
| Property | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| path | string | For `value`: the field title (leading slash optional, e.g. `/Supplier country`). For `cells`: the table field title (e.g. `Line_items`). |
| value | string | The new value for a scalar field. |
| cells | array | Cell-level updates for a table/list field. |
#### cells entries
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------- |
| rowIndex | number | Yes | Zero-based row index within the table |
| column | string | Yes | Column title — must match one of the table's columns |
| value | string | Yes | The new cell value |
## Example
```json theme={null}
{
"schemaValueId": "6a4bac981923768a61f47354",
"fieldPaths": [
{ "path": "/Supplier country", "value": "Netherlands" },
{
"path": "Line_items",
"cells": [
{ "rowIndex": 0, "column": "gl_code", "value": "1234" },
{ "rowIndex": 1, "column": "gl_code", "value": "5678" }
]
}
]
}
```
## How table updates are applied
Table updates are a full read-modify-write. The complete CSV-backed rows are
loaded, the specified cells are applied, and the table is re-persisted —
updating the preview, document history, audit trail, and re-flattening the
document. Avoid issuing concurrent updates against the same table.
This endpoint accepts an optional `Idempotency-Key` request header so a retry
cannot apply the change twice. See
[Idempotent requests](/docs-api/api-idempotency).
## Errors
A `422` is returned for an invalid `fileId`, an invalid or missing
`schemaValueId`, empty or malformed `fieldPaths`, an unknown field path or
column, or a `rowIndex` outside the table's row range. See
[Error responses](/docs-api/api-errors).
## OpenAPI
````yaml patch /prod/v1/files/{fileId}/values
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/files/{fileId}/values:
patch:
tags:
- Public API V1
summary: Update a file's extracted values (fields and table/list cells)
description: >-
Update document form values for a file, for both scalar fields and
table/list cells.
The `schemaValueId` field is the `id` returned by `GET
/files/:fileId/values` (the form value id).
The `fieldPaths` field is an array of updates. Each entry must specify
**exactly one** of:
- `value`: the new value for a scalar field. The `path` is the field
title (the leading slash is optional, e.g. `/Supplier country`).
- `cells`: cell-level updates for a table/list field. The `path` is the
table field title (e.g. `Line_items`). Each cell contains:
- `rowIndex`: the zero-based row index within the table.
- `column`: the column title (must match one of the table columns).
- `value`: the new cell value.
Table updates are a full read-modify-write: the complete CSV-backed rows
are loaded, the specified cells are applied, and the table is
re-persisted (updating the preview, document history, audit trail, and
re-flattening the document).
operationId: PublicAPIController_updateFileValues
parameters:
- name: fileId
required: true
in: path
schema:
type: string
- name: Idempotency-Key
in: header
description: >-
Optional opaque key (max 255 chars, UUIDv4 recommended) making this
request idempotent for 24h: a retry with the same key and body
replays the original response with Idempotent-Replayed: true.
required: false
schema:
type: string
requestBody:
required: true
description: The file values to update
content:
application/json:
schema:
type: string
examples:
example1:
summary: Scalar field and table cells
value:
schemaValueId: 6a4bac981923768a61f47354
fieldPaths:
- path: /Supplier country
value: Netherlands
- path: Line_items
cells:
- rowIndex: 0
column: gl_code
value: '1234'
- rowIndex: 1
column: gl_code
value: '5678'
responses:
'200':
description: The file values are updated
content:
application/json:
example:
success: true
schema:
type: object
properties:
success:
type: boolean
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: >-
Invalid fileId | Invalid schemaValueId | Invalid fieldPaths |
Unknown field path or column | rowIndex out of range
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid schemaValueId.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid schemaValueId.
error: Unprocessable Entity
statusCode: 422
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````