Create Schema

curl --request POST \
  --url https://api.contextual.ai/v1/extract/schemas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "schema_definition": {
    "properties": {
      "company_name": {
        "description": "The name of the company exactly as it appears in the document",
        "type": "string"
      },
      "form_type": {
        "description": "The type of SEC form",
        "enum": [
          "10-K",
          "10-Q",
          "8-K",
          "S-1"
        ],
        "type": "string"
      },
      "trading_symbol": {
        "description": "The trading symbol of the company",
        "type": "string"
      },
      "zip_code": {
        "description": "The zip code of the company headquarters",
        "type": "integer"
      }
    },
    "required": [
      "company_name",
      "form_type",
      "trading_symbol",
      "zip_code"
    ],
    "type": "object"
  },
  "description": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.contextual.ai/v1/extract/schemas"

payload = {
    "name": "<string>",
    "schema_definition": {
        "properties": {
            "company_name": {
                "description": "The name of the company exactly as it appears in the document",
                "type": "string"
            },
            "form_type": {
                "description": "The type of SEC form",
                "enum": ["10-K", "10-Q", "8-K", "S-1"],
                "type": "string"
            },
            "trading_symbol": {
                "description": "The trading symbol of the company",
                "type": "string"
            },
            "zip_code": {
                "description": "The zip code of the company headquarters",
                "type": "integer"
            }
        },
        "required": ["company_name", "form_type", "trading_symbol", "zip_code"],
        "type": "object"
    },
    "description": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    schema_definition: {
      properties: {
        company_name: {
          description: 'The name of the company exactly as it appears in the document',
          type: 'string'
        },
        form_type: {
          description: 'The type of SEC form',
          enum: ['10-K', '10-Q', '8-K', 'S-1'],
          type: 'string'
        },
        trading_symbol: {description: 'The trading symbol of the company', type: 'string'},
        zip_code: {description: 'The zip code of the company headquarters', type: 'integer'}
      },
      required: ['company_name', 'form_type', 'trading_symbol', 'zip_code'],
      type: 'object'
    },
    description: '<string>',
    metadata: {}
  })
};

fetch('https://api.contextual.ai/v1/extract/schemas', 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.contextual.ai/v1/extract/schemas",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'schema_definition' => [
        'properties' => [
                'company_name' => [
                                'description' => 'The name of the company exactly as it appears in the document',
                                'type' => 'string'
                ],
                'form_type' => [
                                'description' => 'The type of SEC form',
                                'enum' => [
                                                                '10-K',
                                                                '10-Q',
                                                                '8-K',
                                                                'S-1'
                                ],
                                'type' => 'string'
                ],
                'trading_symbol' => [
                                'description' => 'The trading symbol of the company',
                                'type' => 'string'
                ],
                'zip_code' => [
                                'description' => 'The zip code of the company headquarters',
                                'type' => 'integer'
                ]
        ],
        'required' => [
                'company_name',
                'form_type',
                'trading_symbol',
                'zip_code'
        ],
        'type' => 'object'
    ],
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.contextual.ai/v1/extract/schemas"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.contextual.ai/v1/extract/schemas")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.contextual.ai/v1/extract/schemas")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "schema_id": "<string>",
  "name": "<string>",
  "schema_definition": {},
  "metadata": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "description": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

/extract

Create Schema

Create a new extraction schema.

Creates a JSON Schema that defines the structure of data to extract from documents. The schema must conform to our supported subset of JSON Schema 2020-12 features.

Supported Schema Features:

Basic Types:

string: Text data with optional constraints (minLength, maxLength, pattern, enum)
integer: Whole numbers with optional constraints (minimum, maximum, enum)
number: Decimal numbers with optional constraints (minimum, maximum, enum)
boolean: True/false values
null: Null values (often used with anyOf for optional fields)

Complex Types:

object: Key-value pairs with defined properties
array: Lists of items with defined item schemas
anyOf: Union types (e.g., string or null for optional fields)

String Formats:

Supported formats: date-time, time, date, duration, email, hostname, ipv4, ipv6, uuid, uri

Schema Structure:

Root schema must be an object type
Use $defs for reusable schema components
Use $ref to reference definitions
Arrays must have items schema defined

Constraints:

Maximum 10 leaf nodes per array (prevents overly complex schemas)
No circular references in $ref definitions
String formats must be from the supported list

Example Schemas:

Simple Company Schema:

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "description": "The name of the company exactly as it appears in the document"
    },
    "form_type": {
      "type": "string",
      "enum": ["10-K", "10-Q", "8-K", "S-1"],
      "description": "The type of SEC form"
    },
    "trading_symbol": {
      "type": "string",
      "description": "The trading symbol of the company"
    },
    "zip_code": {
      "type": "integer",
      "description": "The zip code of the company headquarters"
    }
  },
  "required": ["company_name", "form_type", "trading_symbol", "zip_code"]
}

Complex Resume Schema:

{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "fullName": {"type": "string"},
        "contact": {
          "type": "object",
          "properties": {
            "emails": {
              "type": "array",
              "items": {"type": "string", "format": "email"}
            },
            "phones": {
              "type": "array",
              "items": {"type": "string"}
            }
          }
        }
      },
      "required": ["fullName"]
    },
    "workExperience": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "jobTitle": {"type": "string"},
          "company": {"type": "string"},
          "startDate": {"type": "string"},
          "endDate": {"type": ["string", "null"]},
          "isCurrent": {"type": "boolean"}
        },
        "required": ["jobTitle", "company", "startDate"]
      }
    }
  },
  "required": ["personalInfo", "workExperience"]
}

Schema with References:

{
  "type": "object",
  "properties": {
    "algorithms": {
      "type": "array",
      "items": {"$ref": "#/$defs/algorithm"}
    }
  },
  "$defs": {
    "algorithm": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["name"]
    }
  }
}

Best Practices:

Use descriptive field names that clearly indicate what data should be extracted
Add detailed descriptions to help the AI understand what to extract
Use enum for known values (e.g., form types, status values)
Make fields optional by using anyOf with null or omitting from required
Use arrays for lists of similar items (e.g., work experience, education)
Keep schemas focused - avoid overly complex nested structures
Test with sample documents to ensure the schema captures the expected data

POST

extract

schemas

Create Schema

curl --request POST \
  --url https://api.contextual.ai/v1/extract/schemas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "schema_definition": {
    "properties": {
      "company_name": {
        "description": "The name of the company exactly as it appears in the document",
        "type": "string"
      },
      "form_type": {
        "description": "The type of SEC form",
        "enum": [
          "10-K",
          "10-Q",
          "8-K",
          "S-1"
        ],
        "type": "string"
      },
      "trading_symbol": {
        "description": "The trading symbol of the company",
        "type": "string"
      },
      "zip_code": {
        "description": "The zip code of the company headquarters",
        "type": "integer"
      }
    },
    "required": [
      "company_name",
      "form_type",
      "trading_symbol",
      "zip_code"
    ],
    "type": "object"
  },
  "description": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.contextual.ai/v1/extract/schemas"

payload = {
    "name": "<string>",
    "schema_definition": {
        "properties": {
            "company_name": {
                "description": "The name of the company exactly as it appears in the document",
                "type": "string"
            },
            "form_type": {
                "description": "The type of SEC form",
                "enum": ["10-K", "10-Q", "8-K", "S-1"],
                "type": "string"
            },
            "trading_symbol": {
                "description": "The trading symbol of the company",
                "type": "string"
            },
            "zip_code": {
                "description": "The zip code of the company headquarters",
                "type": "integer"
            }
        },
        "required": ["company_name", "form_type", "trading_symbol", "zip_code"],
        "type": "object"
    },
    "description": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    schema_definition: {
      properties: {
        company_name: {
          description: 'The name of the company exactly as it appears in the document',
          type: 'string'
        },
        form_type: {
          description: 'The type of SEC form',
          enum: ['10-K', '10-Q', '8-K', 'S-1'],
          type: 'string'
        },
        trading_symbol: {description: 'The trading symbol of the company', type: 'string'},
        zip_code: {description: 'The zip code of the company headquarters', type: 'integer'}
      },
      required: ['company_name', 'form_type', 'trading_symbol', 'zip_code'],
      type: 'object'
    },
    description: '<string>',
    metadata: {}
  })
};

fetch('https://api.contextual.ai/v1/extract/schemas', 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.contextual.ai/v1/extract/schemas",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'schema_definition' => [
        'properties' => [
                'company_name' => [
                                'description' => 'The name of the company exactly as it appears in the document',
                                'type' => 'string'
                ],
                'form_type' => [
                                'description' => 'The type of SEC form',
                                'enum' => [
                                                                '10-K',
                                                                '10-Q',
                                                                '8-K',
                                                                'S-1'
                                ],
                                'type' => 'string'
                ],
                'trading_symbol' => [
                                'description' => 'The trading symbol of the company',
                                'type' => 'string'
                ],
                'zip_code' => [
                                'description' => 'The zip code of the company headquarters',
                                'type' => 'integer'
                ]
        ],
        'required' => [
                'company_name',
                'form_type',
                'trading_symbol',
                'zip_code'
        ],
        'type' => 'object'
    ],
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.contextual.ai/v1/extract/schemas"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.contextual.ai/v1/extract/schemas")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.contextual.ai/v1/extract/schemas")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"schema_definition\": {\n    \"properties\": {\n      \"company_name\": {\n        \"description\": \"The name of the company exactly as it appears in the document\",\n        \"type\": \"string\"\n      },\n      \"form_type\": {\n        \"description\": \"The type of SEC form\",\n        \"enum\": [\n          \"10-K\",\n          \"10-Q\",\n          \"8-K\",\n          \"S-1\"\n        ],\n        \"type\": \"string\"\n      },\n      \"trading_symbol\": {\n        \"description\": \"The trading symbol of the company\",\n        \"type\": \"string\"\n      },\n      \"zip_code\": {\n        \"description\": \"The zip code of the company headquarters\",\n        \"type\": \"integer\"\n      }\n    },\n    \"required\": [\n      \"company_name\",\n      \"form_type\",\n      \"trading_symbol\",\n      \"zip_code\"\n    ],\n    \"type\": \"object\"\n  },\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "schema_id": "<string>",
  "name": "<string>",
  "schema_definition": {},
  "metadata": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "description": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for creating a new extraction schema.

The schema_definition must be a valid JSON Schema that defines the structure of data to extract from documents. The system supports a subset of JSON Schema 2020-12 features optimized for document extraction.

name

string

required

Name of the schema

schema_definition

Schema Definition · object

required

JSON Schema definition. Must be a valid JSON Schema that defines the structure of data to extract from documents. See the comprehensive schema guide in the API documentation for detailed examples and supported features.

Example:

{
  "properties": {
    "company_name": {
      "description": "The name of the company exactly as it appears in the document",
      "type": "string"
    },
    "form_type": {
      "description": "The type of SEC form",
      "enum": ["10-K", "10-Q", "8-K", "S-1"],
      "type": "string"
    },
    "trading_symbol": {
      "description": "The trading symbol of the company",
      "type": "string"
    },
    "zip_code": {
      "description": "The zip code of the company headquarters",
      "type": "integer"
    }
  },
  "required": [
    "company_name",
    "form_type",
    "trading_symbol",
    "zip_code"
  ],
  "type": "object"
}

description

string | null

Description of the schema

metadata

Metadata · object | null

Additional metadata for the schema

Response

Successful Response

Response model for schema information.

schema_id

string

required

Unique ID of the schema

name

string

required

Name of the schema

schema_definition

Schema Definition · object

required

JSON schema definition

metadata

Metadata · object

required

Schema metadata

created_at

string

required

Timestamp when the schema was created

updated_at

string

required

Timestamp when the schema was last updated

description

string | null

Description of the schema

/datastores

/datastores/{id}/documents

/agents

/contents

/agents/{id}/query

/lmunit

/users

/generate

/rerank

/parse

/extract

/workspaces

/billing

Create Schema

Authorizations

Body

Response