Skip to content
ParseHawkParseHawk Developer Docs

Get an extractor

GET
/v1/extractors/{extractor_ref}
curl --request GET \
  --url http://127.0.0.1:8000/v1/extractors/example

Retrieve an extractor by immutable ID or stable name.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
extractor_ref
required
Extractor Ref

Extractor ID or stable name.

string

Extractor ID or stable name.

Responses

Section titled “Responses”

200

Section titled “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

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
required
Any of:
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
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

Section titled “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
Examplegenerated
{
  "detail": [
    {}
  ]
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}

500

Section titled “500”

Unexpected server error.

Media typeapplication/json
ApiErrorResponse

Error returned by request validation or a ParseHawk domain service.

object
detail
required
Any of:
string
Examplegenerated
{
  "detail": [
    {}
  ]
}