Update an extractor

PATCH

/v1/extractors/{extractor_ref}

curl --request PATCH \
  --url http://127.0.0.1:8000/v1/extractors/example \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "instructions": "example", "reasoning_effort": "none", "provider_name": "openai", "model": "example", "schema": {}, "examples": [ { "input": { "type": "text", "text": "example", "file_id": "example" }, "output": {} } ] }'

• Default local ParseHawk API

Partially update a custom extractor while preserving omitted fields.

Parameters

Path Parameters

extractor_ref

required

Extractor Ref

Extractor ID or stable name.

string

Extractor ID or stable name.

Request Body^required

Media typeapplication/json

UpdateExtractorRequest

Partial update for an existing extractor.

object

display_name

Any of:

string

string

null

null

instructions

Any of:

string

string

null

null

reasoning_effort

Any of:

ReasoningEffort

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

null

null

provider_name

Any of:

ProviderName

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

null

null

model

Any of:

string

string

null

null

schema

Any of:

object

object

key

additional properties

any

null

null

examples

Any of:

Array<object>

Array<object>

ExampleRequest

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

object

input

required

Any of:

ExampleInputRequest

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

string

null

null

file_id

Any of:

string

string

null

null

string

string

output

required

Any of:

object

object

key

additional properties

any

string

string

null

null

Responses

200

Successful Response

Media typeapplication/json

ExtractorResponse

Public representation of a reusable extractor.

object

id

required

Id

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

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

null

null

provider_name

required

Any of:

ProviderName

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

null

null

model

required

Any of:

string

string

null

null

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"
}

404

The requested ParseHawk resource does not exist.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "detail": [
    {}
  ]
}

422

The request or domain input failed validation.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "detail": [
    {}
  ]
}

500

Unexpected server error.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "detail": [
    {}
  ]
}