Create or replace a parser

PUT

/v1/parsers/{parser_ref}

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

• Default local ParseHawk API

Create a named parser when absent or replace its complete definition when present.

Parameters

Path Parameters

parser_ref

required

Parser Ref

Stable parser name.

string

Stable parser name.

Request Body^required

Media typeapplication/json

UpsertParserRequest

Complete parser definition used to create or replace a parser by reference.

object

name

Any of:

string

string

null

null

display_name

required

Display Name

Human-readable parser label.

string

output_format

ParserOutputFormat

Output format produced by the parser.

string

default: markdown

Allowed values: markdown

instructions

Instructions

Document parsing instructions.

string

""

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

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": [
    {}
  ]
}