Update a file's schema field definitions

curl --request PATCH \
  --url https://api.orion.file.ai/prod/v1/files/schema \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileId": "f739da3b-d8cb-4f62-8174-4d387c28a5ac",
  "schemaId": "689eaa87aea205bcfc0f0201",
  "shouldCreateCustomIfNotExists": true,
  "schemaVersionType": "MINOR",
  "shouldChangeDocumentToNewSchemaVersion": true,
  "fieldPaths": [
    {
      "path": "/Receipt Number",
      "mode": "CREATE",
      "attributes": {
        "type": "string",
        "title": "Receipt Number",
        "hidden": false,
        "internet_context": false,
        "enumValues": [],
        "description": "Receipt Number"
      }
    }
  ]
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/schema"

payload = {
    "fileId": "f739da3b-d8cb-4f62-8174-4d387c28a5ac",
    "schemaId": "689eaa87aea205bcfc0f0201",
    "shouldCreateCustomIfNotExists": True,
    "schemaVersionType": "MINOR",
    "shouldChangeDocumentToNewSchemaVersion": True,
    "fieldPaths": [
        {
            "path": "/Receipt Number",
            "mode": "CREATE",
            "attributes": {
                "type": "string",
                "title": "Receipt Number",
                "hidden": False,
                "internet_context": False,
                "enumValues": [],
                "description": "Receipt Number"
            }
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileId: 'f739da3b-d8cb-4f62-8174-4d387c28a5ac',
    schemaId: '689eaa87aea205bcfc0f0201',
    shouldCreateCustomIfNotExists: true,
    schemaVersionType: 'MINOR',
    shouldChangeDocumentToNewSchemaVersion: true,
    fieldPaths: [
      {
        path: '/Receipt Number',
        mode: 'CREATE',
        attributes: {
          type: 'string',
          title: 'Receipt Number',
          hidden: false,
          internet_context: false,
          enumValues: [],
          description: 'Receipt Number'
        }
      }
    ]
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/schema', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/schema",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'fileId' => 'f739da3b-d8cb-4f62-8174-4d387c28a5ac',
    'schemaId' => '689eaa87aea205bcfc0f0201',
    'shouldCreateCustomIfNotExists' => true,
    'schemaVersionType' => 'MINOR',
    'shouldChangeDocumentToNewSchemaVersion' => true,
    'fieldPaths' => [
        [
                'path' => '/Receipt Number',
                'mode' => 'CREATE',
                'attributes' => [
                                'type' => 'string',
                                'title' => 'Receipt Number',
                                'hidden' => false,
                                'internet_context' => false,
                                'enumValues' => [
                                                                
                                ],
                                'description' => 'Receipt Number'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/files/schema"

	payload := strings.NewReader("{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.orion.file.ai/prod/v1/files/schema")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/files/schema")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "689eaa87aea205bcfc0f0201",
  "fields": [
    {
      "id": "689eaa87aea205bcfc0f0201",
      "name": "Receipt Number",
      "type": "string",
      "title": "Receipt Number",
      "hidden": false,
      "internet_context": false,
      "enumValues": [],
      "description": "Receipt Number"
    }
  ],
  "blueprintId": "689eaa87aea205bcfc0f0201",
  "originalSchemaId": "689eaa87aea205bcfc0f0201",
  "schemaHistoryId": "689eaa87aea205bcfc0f0201",
  "schemaHistoryVersionNumber": 1,
  "fileId": "689eaa87aea205bcfc0f0201",
  "blueprintMode": "USER",
  "schemaType": "SYSTEM",
  "state": "ACTIVE",
  "usageApprovalState": "DRAFT",
  "schemaOverrideType": "NONE",
  "aiSchemaVersion": "v3",
  "createdAt": "2025-03-31T09:50:56.068Z",
  "updatedAt": "2025-03-31T09:50:56.068Z"
}

Endpoints

Update a file's schema field definitions

This endpoint is used to patch the schema fields that are associated with the file types in the workspace.

The response will contain a list of schemas that are associated with the file types in the workspace.

The fileId field is used to specify the file that should be changed to the new schema version.

The schemaId field is used to specify the schema that should be updated.

The shouldCreateCustomIfNotExists field is used to specify whether a custom schema should be created if it does not exist.

The schemaVersionType field is used to specify the type of schema version to be create. The allowed values are MAJOR, MINOR, and PATCH.

The shouldChangeDocumentToNewSchemaVersion field is used to specify whether the document should be changed to the new schema version.

The fieldPaths field is used to specify the fields that should be updated.

PATCH

prod

files

schema

Update a file's schema field definitions

curl --request PATCH \
  --url https://api.orion.file.ai/prod/v1/files/schema \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileId": "f739da3b-d8cb-4f62-8174-4d387c28a5ac",
  "schemaId": "689eaa87aea205bcfc0f0201",
  "shouldCreateCustomIfNotExists": true,
  "schemaVersionType": "MINOR",
  "shouldChangeDocumentToNewSchemaVersion": true,
  "fieldPaths": [
    {
      "path": "/Receipt Number",
      "mode": "CREATE",
      "attributes": {
        "type": "string",
        "title": "Receipt Number",
        "hidden": false,
        "internet_context": false,
        "enumValues": [],
        "description": "Receipt Number"
      }
    }
  ]
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/schema"

payload = {
    "fileId": "f739da3b-d8cb-4f62-8174-4d387c28a5ac",
    "schemaId": "689eaa87aea205bcfc0f0201",
    "shouldCreateCustomIfNotExists": True,
    "schemaVersionType": "MINOR",
    "shouldChangeDocumentToNewSchemaVersion": True,
    "fieldPaths": [
        {
            "path": "/Receipt Number",
            "mode": "CREATE",
            "attributes": {
                "type": "string",
                "title": "Receipt Number",
                "hidden": False,
                "internet_context": False,
                "enumValues": [],
                "description": "Receipt Number"
            }
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileId: 'f739da3b-d8cb-4f62-8174-4d387c28a5ac',
    schemaId: '689eaa87aea205bcfc0f0201',
    shouldCreateCustomIfNotExists: true,
    schemaVersionType: 'MINOR',
    shouldChangeDocumentToNewSchemaVersion: true,
    fieldPaths: [
      {
        path: '/Receipt Number',
        mode: 'CREATE',
        attributes: {
          type: 'string',
          title: 'Receipt Number',
          hidden: false,
          internet_context: false,
          enumValues: [],
          description: 'Receipt Number'
        }
      }
    ]
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/schema', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/schema",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'fileId' => 'f739da3b-d8cb-4f62-8174-4d387c28a5ac',
    'schemaId' => '689eaa87aea205bcfc0f0201',
    'shouldCreateCustomIfNotExists' => true,
    'schemaVersionType' => 'MINOR',
    'shouldChangeDocumentToNewSchemaVersion' => true,
    'fieldPaths' => [
        [
                'path' => '/Receipt Number',
                'mode' => 'CREATE',
                'attributes' => [
                                'type' => 'string',
                                'title' => 'Receipt Number',
                                'hidden' => false,
                                'internet_context' => false,
                                'enumValues' => [
                                                                
                                ],
                                'description' => 'Receipt Number'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/files/schema"

	payload := strings.NewReader("{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.orion.file.ai/prod/v1/files/schema")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/files/schema")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileId\": \"f739da3b-d8cb-4f62-8174-4d387c28a5ac\",\n  \"schemaId\": \"689eaa87aea205bcfc0f0201\",\n  \"shouldCreateCustomIfNotExists\": true,\n  \"schemaVersionType\": \"MINOR\",\n  \"shouldChangeDocumentToNewSchemaVersion\": true,\n  \"fieldPaths\": [\n    {\n      \"path\": \"/Receipt Number\",\n      \"mode\": \"CREATE\",\n      \"attributes\": {\n        \"type\": \"string\",\n        \"title\": \"Receipt Number\",\n        \"hidden\": false,\n        \"internet_context\": false,\n        \"enumValues\": [],\n        \"description\": \"Receipt Number\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "689eaa87aea205bcfc0f0201",
  "fields": [
    {
      "id": "689eaa87aea205bcfc0f0201",
      "name": "Receipt Number",
      "type": "string",
      "title": "Receipt Number",
      "hidden": false,
      "internet_context": false,
      "enumValues": [],
      "description": "Receipt Number"
    }
  ],
  "blueprintId": "689eaa87aea205bcfc0f0201",
  "originalSchemaId": "689eaa87aea205bcfc0f0201",
  "schemaHistoryId": "689eaa87aea205bcfc0f0201",
  "schemaHistoryVersionNumber": 1,
  "fileId": "689eaa87aea205bcfc0f0201",
  "blueprintMode": "USER",
  "schemaType": "SYSTEM",
  "state": "ACTIVE",
  "usageApprovalState": "DRAFT",
  "schemaOverrideType": "NONE",
  "aiSchemaVersion": "v3",
  "createdAt": "2025-03-31T09:50:56.068Z",
  "updatedAt": "2025-03-31T09:50:56.068Z"
}

It is used to change the file schema to a new version, and update the file fields accordingly. The shouldChangeDocumentToNewSchemaVersion flag is used to determine whether the file should be updated to the new schema version.

If set to true, the file will be updated to the new schema version.
If set to false, the file will not be updated, and the new schema version will be created as a new schema version.

The shouldCreateCustomIfNotExists flag is used to determine whether a custom schema should be created if the file does not have a custom schema.

If set to true, a custom schema will be created if the file does not have a custom schema.
If set to false, no custom schema will be created.

The schemaVersionType field is used to determine the type of schema version that should be created.

The allowed values are MAJOR, MINOR, and PATCH.

The fieldPaths field is used to specify the fields that should be updated in the file.

The fields that are specified in the fieldPaths field will be updated with the new schema fields.
If a field is not specified in the fieldPaths field, the field will not be updated.

This endpoint accepts an optional Idempotency-Key request header so a retry cannot apply the change twice. See Idempotent requests.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

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.

Body

application/json

Update file schema

The body is of type string.

Response

The schema is patched

string

fields

object[]

blueprintId

string

originalSchemaId

string

schemaHistoryId

string

schemaHistoryVersionNumber

number

fileId

string

blueprintMode

string

schemaType

string

state

string

usageApprovalState

string

schemaOverrideType

string

aiSchemaVersion

string

createdAt

string

updatedAt

string

deletedAt

string

deletedBy

string

⌘I

fileAI API

Key Functions

Endpoints

Update a file's schema field definitions

Authorizations

Headers

Body

Response