Create a job

POST

/v1/jobs

Code sample: curl

API="${PARSEHAWK_API_URL:-http://127.0.0.1:8000}"
curl --fail --silent --show-error \
  --request POST "$API/v1/jobs" \
  --header "Content-Type: application/json" \
  --data '{"extractor_name":"receipt","file_id":"file_..."}' | jq .

• Default local ParseHawk API

Enqueue extraction for one uploaded file or inline text input.

Request Body^required

Media typeapplication/json

CreateJobRequest

Request to enqueue one extraction job.

object

extractor_id

Any of:

string

string

null

null

extractor_name

Any of:

string

string

null

null

file_id

Any of:

string

string

null

null

text

Any of:

string

string

null

null

Responses

201

Successful Response

Media typeapplication/json

JobResponse

Current state and eventual result of one extraction job.

object

id

required

Id

Immutable job identifier.

string

extractor_id

required

Extractor Id

Immutable extractor identifier used by the job.

string

file_id

required

Any of:

string

string

null

null

source_text

required

Any of:

string

string

null

null

provider_name_used

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_used

required

Any of:

string

string

null

null

status

required

JobStatus

Current job lifecycle state.

string

Allowed values: queued running completed failed canceling deleting canceled

result

required

Any of:

JobResultResponse

JobResultResponse

Validated structured output produced by an extraction job.

object

data

required

Data

Result validated against the extractor schema.

object

key

additional properties

any

null

null

error

required

Any of:

JobErrorResponse

JobErrorResponse

Terminal extraction error stored with a failed job.

object

message

required

Message

Human-readable failure message.

string

code

required

Code

Stable machine-readable failure code.

string

null

null

created_at

required

Created At

UTC creation time.

string format: date-time

started_at

required

Any of:

string

string format: date-time

null

null

completed_at

required

Any of:

string

string format: date-time

null

null

Example

{
  "id": "job_01JZ6QK8M7",
  "provider_name_used": "openai",
  "status": "queued"
}

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