Update a parser

PATCH

/v1/parsers/{parser_ref}

curl --request PATCH \
  --url http://127.0.0.1:8000/v1/parsers/example \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "output_format": "markdown", "instructions": "example", "reasoning_effort": "none", "provider_name": "openai", "model": "example" }'

• Default local ParseHawk API

Partially update a custom parser while preserving omitted fields.

Parameters

Path Parameters

parser_ref

required

Parser Ref

Parser ID or stable name.

string

Parser ID or stable name.

Request Body^required

Media typeapplication/json

UpdateParserRequest

Partial update for an existing parser.

object

display_name

Any of:

string

string

null

null

output_format

Any of:

ParserOutputFormat

ParserOutputFormat

string

Allowed values: markdown

null

null

instructions

Any of:

string

string

null

null

reasoning_effort

Any of:

ReasoningEffort

ReasoningEffort

Explicit reasoning effort for an extractor’s or parser’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

Responses

200

Successful Response

Media typeapplication/json

ParserResponse

Public representation of a reusable parser.

object

id

required

Id

Immutable parser identifier.

string

name

required

Name

Stable URL-safe parser name.

string

display_name

required

Display Name

Human-readable parser label.

string

output_format

required

ParserOutputFormat

Configured parser output format.

string

Allowed values: markdown

instructions

required

Instructions

Document parsing instructions.

string

reasoning_effort

required

Any of:

ReasoningEffort

ReasoningEffort

Explicit reasoning effort for an extractor’s or parser’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

source

required

ParserSource

How the parser was created.

string

Allowed values: user prebuilt

is_prebuilt

required

Is Prebuilt

Whether ParseHawk ships this parser.

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

{
  "output_format": "markdown",
  "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

code

Any of:

string

string

null

null

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": [
    {}
  ]
}

422

The request or domain input failed validation.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

code

Any of:

string

string

null

null

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": [
    {}
  ]
}

500

Unexpected server error.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

code

Any of:

string

string

null

null

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": [
    {}
  ]
}

503

Persistence is temporarily busy and the request can be retried.

Media typeapplication/json

ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object

code

Any of:

string

string

null

null

detail

required

Any of:

string

string

Array<object>

Array<object>

object

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": [
    {}
  ]
}