> ## 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.
# [Deprecated] Patch workspace schema field definitions
> **Deprecated.** To update extracted field values of a file — including regular fields (string, number, enum, date, boolean) and list/table cell values — use `PATCH /files/{fileId}/values` instead.
This endpoint remains available for patching schema field definitions, but will be removed in a future version.
This endpoint is used to patch a schema.
The `schemaId` field is used to specify the schema that should be patched. The `fields` field is used to specify the fields that should be updated.
The `fields` field is an array of fields. Each field contains the following fields:
- `title`: The title of the field. This is the human-readable name of the field.
- `description`: The description of the field. This is a human-readable description of the field.
- `type`: The type of the field. This can be either STRING, NUMBER, BOOLEAN, DATE, or OBJECT.
- `format`: The format of the field. This is a string that indicates the format of the field.
- `hidden`: Whether the field is hidden or not. This is a boolean value that indicates whether the field is hidden or not.
- `internet_context`: Whether the field is internet context or not. This is a boolean value that indicates whether the field is internet context or not.
- `fieldSuggestion`: The field suggestion of the field. This is an object that contains the following fields:
- `id`: The ID of the field suggestion. This is the unique identifier for the field suggestion.
- `name`: The name of the field suggestion. This is the human-readable name of the field suggestion.
- `items`: The items of the field. This is an array of fields that are the items of the field.
- `value`: The value of the field. This is the value of the field.
- `enumValues`: The enum values of the field. This is an array of strings that are the enum values of the field.
- `inlineListType`: The inline list type of the field. This is a string that indicates the inline list type of the field.
**Deprecated for updating extracted values.** To update the extracted field
values of a file — regular fields (string, number, enum, date, boolean) as well
as list/table cell values — use
[`PATCH /files/{fileId}/values`](/api-reference/endpoint/update-file-values)
instead.
This endpoint remains available for patching schema field *definitions*, but
will be removed in a future version. Migrate value updates now.
The **schemaId** field is used to specify the schema that should be patched.
The **fields** field is used to specify the fields that should be updated.
The **fields** field is an array of fields.
Each field contains the following fields:
* **title**: The title of the field. This is the human-readable name of the field.
* **description**: The description of the field. This is a human-readable description of the field.
* **type**: The type of the field. This can be either STRING, NUMBER, BOOLEAN, DATE, or OBJECT.
* **format**: The format of the field. This is a string that indicates the format of the field.
* **hidden**: Whether the field is hidden or not. This is a boolean value that indicates whether the field is hidden or not.
* **internet\_context**: Whether the field is internet context or not. This is a boolean value that indicates whether the field is internet context or not.
* **fieldSuggestion**: The field suggestion of the field. This is an object that contains the following fields:
* **id**: The ID of the field suggestion. This is the unique identifier for the field suggestion.
* **name**: The name of the field suggestion. This is the human-readable name of the field suggestion.
* **items**: The items of the field. This is an array of fields that are the items of the field.
* **value**: The value of the field. This is the value of the field.
* **enumValues**: The enum values of the field. This is an array of strings that are the enum values of the field.
* **inlineListType**: The inline list type of the field. This is a string that indicates the inline list type of the field.
## Request Body
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------- |
| schemaId | string | Yes | Unique identifier of the schema to update |
| fields | array | Yes | Array of field objects to update or add |
### Field Object Structure
Each field in the `fields` array can contain the following properties:
| Property | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------------- |
| title | string | No | Human-readable name of the field |
| description | string | No | Detailed description of the field's purpose |
| type | string | No | Data type: STRING, NUMBER, BOOLEAN, DATE, or OBJECT |
| format | string | No | Specific format specification for the field |
| hidden | boolean | No | Whether the field should be hidden from display |
| internet\_context | boolean | No | Whether the field relates to internet/web context |
| fieldSuggestion | object | No | Suggested values configuration |
| items | array | No | For array/list fields, defines the structure of list items |
| value | any | No | Default or current value of the field |
| enumValues | array | No | Array of allowed string values for enum fields |
| inlineListType | string | No | Type specification for inline list formatting |
### Field Object Structure
Each field in the `fields` array can contain the following properties:
| Property | Type | Description |
| -------- | ------ | ------------------------------------ |
| id | string | Unique identifier for the suggestion |
| name | string | Display name for the suggestion |
## Example Request
```json theme={null}
{
"schemaId": "user-profile-schema-123",
"fields": [
{
"title": "Full Name",
"description": "User's complete name including first and last name",
"type": "STRING",
"hidden": false,
"value": ""
},
{
"title": "Age",
"description": "User's age in years",
"type": "NUMBER",
"format": "integer",
"hidden": false
},
{
"title": "Account Status",
"description": "Current status of the user account",
"type": "STRING",
"enumValues": ["active", "inactive", "suspended", "pending"],
"fieldSuggestion": {
"id": "status-suggestion-1",
"name": "Account Status Options"
}
},
{
"title": "Preferences",
"description": "User preference settings",
"type": "OBJECT",
"hidden": false,
"items": [
{
"title": "Email Notifications",
"type": "BOOLEAN",
"value": true
}
]
}
]
}
```
This endpoint accepts an optional `Idempotency-Key` request header so a retry
cannot apply the change twice. See
[Idempotent requests](/docs-api/api-idempotency).
## Migrating to PATCH /files/\{fileId}/values
| You want to… | Use |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Change an extracted field value on a file | [`PATCH /files/{fileId}/values`](/api-reference/endpoint/update-file-values) |
| Change a table/list cell value on a file | [`PATCH /files/{fileId}/values`](/api-reference/endpoint/update-file-values) |
| Change a schema's field definitions (title, type, enum values, …) | This endpoint, or [`PATCH /files/schema`](/api-reference/endpoint/update-file-schema) for a single file |
## OpenAPI
````yaml patch /prod/v1/schemas
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/schemas:
patch:
tags:
- Public API V1
summary: '[Deprecated] Patch workspace schema field definitions'
description: >-
**Deprecated.** To update extracted field values of a file — including
regular fields (string, number, enum, date, boolean) and list/table cell
values — use `PATCH /files/{fileId}/values` instead.
This endpoint remains available for patching schema field definitions,
but will be removed in a future version.
This endpoint is used to patch a schema.
The `schemaId` field is used to specify the schema that should be
patched. The `fields` field is used to specify the fields that should be
updated.
The `fields` field is an array of fields. Each field contains the
following fields:
- `title`: The title of the field. This is the human-readable name of
the field.
- `description`: The description of the field. This is a human-readable
description of the field.
- `type`: The type of the field. This can be either STRING, NUMBER,
BOOLEAN, DATE, or OBJECT.
- `format`: The format of the field. This is a string that indicates the
format of the field.
- `hidden`: Whether the field is hidden or not. This is a boolean value
that indicates whether the field is hidden or not.
- `internet_context`: Whether the field is internet context or not. This
is a boolean value that indicates whether the field is internet context
or not.
- `fieldSuggestion`: The field suggestion of the field. This is an
object that contains the following fields:
- `id`: The ID of the field suggestion. This is the unique identifier for the field suggestion.
- `name`: The name of the field suggestion. This is the human-readable name of the field suggestion.
- `items`: The items of the field. This is an array of fields that are
the items of the field.
- `value`: The value of the field. This is the value of the field.
- `enumValues`: The enum values of the field. This is an array of
strings that are the enum values of the field.
- `inlineListType`: The inline list type of the field. This is a string
that indicates the inline list type of the field.
operationId: PublicAPIController_patchSchemaById
parameters:
- 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 schema to patch
content:
application/json:
schema:
type: string
examples:
example1:
value:
schemaId: 5f5f726eea75272d54e1e1e1
fields:
- id: 5f5f726eea75272d54e1e1e2
title: Title
description: Description
type: STRING
format: text
hidden: false
internet_context: false
fieldSuggestion:
id: 5f5f726eea75272d54e1e1e3
name: Field Suggestion
items: []
value: Value
enumValues: []
inlineListType: SINGLE
responses:
'200':
description: The schema is patched
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 schemaId | Invalid fields
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
examples:
Invalid schemaId:
summary: Invalid schemaId
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid schemaId.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid schemaId.
error: Unprocessable Entity
statusCode: 422
Invalid fields:
summary: Invalid fields
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid fields.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid fields.
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'
deprecated: true
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
````