Create an extractor

POST

/v1/extractors

const url = 'http://127.0.0.1:8000/v1/extractors';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"name":"invoice","display_name":"Invoice","instructions":"Extract the invoice header, supplier, and total exactly as shown.","reasoning_effort":"none","provider_name":"openai","model":"gpt-4o-mini","schema":{},"examples":[{"input":{"type":"text","text":"example","file_id":"example"},"output":{}}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://127.0.0.1:8000/v1/extractors \
  --header 'Content-Type: application/json' \
  --data '{ "name": "invoice", "display_name": "Invoice", "instructions": "Extract the invoice header, supplier, and total exactly as shown.", "reasoning_effort": "none", "provider_name": "openai", "model": "gpt-4o-mini", "schema": {}, "examples": [ { "input": { "type": "text", "text": "example", "file_id": "example" }, "output": {} } ] }'

Create a reusable extraction definition from instructions, a schema, and optional examples.

Request Body^required

application/json

CreateExtractorRequest

Definition used to create a reusable extractor.

object

name

Any of:

string
null

string

display_name

Any of:

string
null

string

instructions

required

Instructions

Natural-language extraction instructions.

string

reasoning_effort

Any of:

ReasoningEffort
null

ReasoningEffort

Explicit reasoning effort for an extractor’s model.

The values mirror OpenAI’s reasoning_effort parameter. Extractors store None by default, which means “send no reasoning parameter and use the model’s own default” — the only setting that is safe for every model. Which explicit values a model accepts is the provider’s call; incompatible pairs surface the provider’s error at extraction time.

string

Allowed values: none minimal low medium high xhigh

provider_name

Any of:

ProviderName
null

ProviderName

The fixed set of model providers ParseHawk ships.

Providers are preconfigured and configurable, not user-creatable, so the name doubles as the stable identifier extractors reference and as the discriminator the engine factory switches on.

string

Allowed values: openai microsoft_foundry openai_compatible_api

model

Any of:

string
null

string

schema

required

Schema

JSON Schema that every successful extraction result must satisfy.

object

key

additional properties

any

examples

Examples

Optional few-shot examples for difficult document types.

Array<object>

ExampleRequest

Few-shot example pairing representative input with expected structured output.

object

input

required

Any of:

ExampleInputRequest
string

ExampleInputRequest

Input used by a few-shot extraction example.

object

type

ExampleInputKind

Whether the example input is inline text or a previously uploaded file.

string

default: text

Allowed values: text file

text

Any of:

string
null

string

file_id

Any of:

string
null

string

output

required

Any of:

object
string

object

key

additional properties

any

Responses

201

Successful Response

application/json

ExtractorResponse

Public representation of a reusable extractor.

object

required

Immutable extractor identifier.

string

name

required

Name

Stable URL-safe extractor name.

string

display_name

required

Display Name

Human-readable extractor label.

string

instructions

required

Instructions

Natural-language extraction instructions.

string

reasoning_effort

required

Any of:

ReasoningEffort
null

ReasoningEffort

Explicit reasoning effort for an extractor’s model.

string

Allowed values: none minimal low medium high xhigh

provider_name

required

Any of:

ProviderName
null

ProviderName

The fixed set of model providers ParseHawk ships.

Providers are preconfigured and configurable, not user-creatable, so the name doubles as the stable identifier extractors reference and as the discriminator the engine factory switches on.

string

Allowed values: openai microsoft_foundry openai_compatible_api

model

required

Any of:

string
null

string

schema

required

Schema

Extraction result JSON Schema.

object

key

additional properties

any

examples

required

Examples

Configured few-shot examples.

Array<object>

object

key

additional properties

any

source

required

ExtractorSource

How the extractor was created.

string

Allowed values: user prebuilt

is_prebuilt

required

Is Prebuilt

Whether ParseHawk ships this extractor.

boolean

created_at

required

Created At

UTC creation time.

string format: date-time

updated_at

required

Updated At

UTC last-update time.

string format: date-time

Example

{
  "name": "invoice",
  "reasoning_effort": "none",
  "provider_name": "openai",
  "source": "user"
}

422

The request or domain input failed validation.

application/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

detail

required

Any of:

string
Array<object>

string

Example^generated

{
  "detail": [
    {}
  ]
}

500

Unexpected server error.

application/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

detail

required

Any of:

string
Array<object>

string

Example^generated

{
  "detail": [
    {}
  ]
}

Create an extractor

Request Bodyrequired

Responses

201

Example

422

Examplegenerated

500

Examplegenerated

Request Body^required

Example^generated

Example^generated