Jobs

The Jobs endpoints expose the Orchestrator-managed redaction workflow. A job is created by uploading a PDF; detection then runs automatically, the job moves to readyForReview, a reviewer submits the redaction list, redaction runs, and the redacted PDF is downloadable. The cURL examples use the Orchestrator’s default address (http://localhost:9983); substitute the host and port of your deployment as needed. They also use an $API_KEY shell variable for the API key — refer to Authentication for how to obtain one.

Job lifecycle

Each job progresses through the following statuses. Endpoints that move a job between statuses are noted alongside.

Status	Description	Set by
`created`	The job has been registered. Detection hasn’t started yet.	`POST /v1/jobs`
`detectionInProgress`	Detection is running.	Automatic, after `created`.
`readyForReview`	Detection is complete. A reviewer can now submit the redaction list.	Automatic, when detection finishes.
`redactionInProgress`	Redaction is running.	`POST /v1/jobs/{id}/redaction`
`finished`	Redaction is complete. The redacted PDF is available for download.	Automatic, when redaction finishes.
`expired`	The job has expired and the redacted file is no longer available.	Automatic, when the uploaded PDF expires.
`failed`	An error occurred while processing the job. Details are in the response.	Automatic, on failure.

Endpoints

All endpoints require authentication. Unauthenticated requests receive 401 Unauthorized; refer to the Authentication section for details. The per-endpoint status code tables don’t repeat this.

Create a job

POST /v1/jobs

Creates a new job by uploading a PDF as multipart form data. Detection runs automatically; the response returns the job in created or detectionInProgress status.

Request body (multipart/form-data):

Field	Type	Description
`file`	`binary`	The PDF to redact.

Response — JobResponse.

Status codes:

Code	Meaning
`201`	The job was created.
`400`	The request was malformed or the file couldn’t be read.

Example:

curl -X POST "http://localhost:9983/v1/jobs" \
  -H "X-Api-Key: $API_KEY" \
  -F "file=@document.pdf"

List jobs

GET /v1/jobs

Returns a paginated list of jobs, ordered by most recent first. Supports cursor-based pagination, status filtering, and substring search on the file name.

Query parameters:

Name	Type	Description
`pageSize`	`integer`	Items per page (1–100). Defaults to 20.
`cursor`	`string`	Pagination cursor returned in `nextCursor` on a previous response.
`status`	`JobStatus`	Filter by job status.
`createdBy`	`string`	Filter by creator user ID.
`reviewedBy`	`string`	Filter by reviewer user ID.
`fileName`	`string`	Case-insensitive substring search on the file name.
`sortBy`	`JobSortField`	Sort field. Defaults to `createdAt`.
`sortDirection`	`SortDirection`	Sort direction. Defaults to `desc`.

Response — JobSummaryResponsePaginatedResponse.

Example:

curl "http://localhost:9983/v1/jobs?status=readyForReview&pageSize=50" \
  -H "X-Api-Key: $API_KEY"

Get a job

GET /v1/jobs/{id}

Returns the full details of a job, including the detection result when available.

Path parameters:

Name	Type	Description
`id`	`string` (UUID)	The job ID.

Response — JobResponse.

Status codes:

Code	Meaning
`200`	The job was found.
`404`	No job with the given `id` exists.

Example:

curl "http://localhost:9983/v1/jobs/$JOB_ID" \
  -H "X-Api-Key: $API_KEY"

Start redaction for a job

POST /v1/jobs/{id}/redaction

Submits the reviewed list of entities to redact and starts the redaction step. The job must be in readyForReview.

Path parameters:

Name	Type	Description
`id`	`string` (UUID)	The job ID.

Request body — RedactionInput.

Response — JobResponse, with status updated to redactionInProgress.

Status codes:

Code	Meaning
`200`	Redaction was started.
`404`	No job with the given `id` exists.
`409`	The job isn’t in `readyForReview`.

Example:

curl -X POST "http://localhost:9983/v1/jobs/$JOB_ID/redaction" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redactions": [
      {
        "pageIndex": 0,
        "text": "John",
        "label": "PERSON",
        "score": 0.99,
        "quadrilaterals": [{
          "bottomLeft": {"x": 235.8, "y": 671.8},
          "bottomRight": {"x": 264.0, "y": 671.8},
          "topRight": {"x": 264.0, "y": 682.0},
          "topLeft": {"x": 235.8, "y": 682.0}
        }]
      }
    ]
  }'

Download a job file

GET /v1/jobs/{id}/files/{fileType}

Downloads one of the files associated with a job: the original PDF, the FDF detection annotations, or the redacted output PDF.

Path parameters:

Name	Type	Description
`id`	`string` (UUID)	The job ID.
`fileType`	`JobFileType`	Which file to download.

Response — the file bytes (application/pdf or application/fdf).

Status codes:

Code	Meaning
`200`	The file was returned.
`404`	The job or the requested file type doesn’t exist.
`502`	The Orchestrator couldn’t fetch the file from the Manager.

Example:

curl "http://localhost:9983/v1/jobs/$JOB_ID/files/redactedPdf" \
  -H "X-Api-Key: $API_KEY" \
  --output redacted.pdf

Schemas

`JobResponse` schema

Field	Type	Description
`id`	`string` (UUID)	Job identifier.
`fileName`	`string`	Original file name of the uploaded PDF.
`status`	`JobStatus`	Current job status.
`createdBy`	`UserInfoResponse`	The user that created the job.
`reviewedBy`	`UserInfoResponse`	The user that submitted the redaction list. Set after redaction starts.
`createdAt`	`string` (UTC date-time)	When the job was created.
`updatedAt`	`string` (UTC date-time)	When the job was last updated.
`pdfExpiresAt`	`string` (UTC date-time)	When the uploaded PDF expires. After this point, the job moves to `expired`.
`fdfExpiresAt`	`string` (UTC date-time)	When the detection result (FDF) expires. Set once detection completes.
`redactedPdfExpiresAt`	`string` (UTC date-time)	When the redacted PDF expires. Set once redaction completes.
`detectionResult`	`DetectionResult`	Detected entities. Available once the job reaches `readyForReview`.

`JobSummaryResponse` schema

Field	Type	Description
`id`	`string` (UUID)	Job identifier.
`fileName`	`string`	Original file name of the uploaded PDF.
`status`	`JobStatus`	Current job status.
`createdBy`	`UserInfoResponse`	The user that created the job.
`reviewedBy`	`UserInfoResponse`	The user that submitted the redaction list.
`createdAt`	`string` (UTC date-time)	When the job was created.
`updatedAt`	`string` (UTC date-time)	When the job was last updated.
`pdfExpiresAt`	`string` (UTC date-time)	When the uploaded PDF expires. After this point, the job moves to `expired`.
`fdfExpiresAt`	`string` (UTC date-time)	When the detection result (FDF) expires. Set once detection completes.
`redactedPdfExpiresAt`	`string` (UTC date-time)	When the redacted PDF expires. Set once redaction completes.

`JobSummaryResponsePaginatedResponse` schema

Field	Type	Description
`items`	array of `JobSummaryResponse`	Page of jobs.
`pageSize`	`integer`	Page size that was applied.
`totalCount`	`integer`	Total number of jobs matching the query.
`nextCursor`	`string`	Cursor to pass on the next call. Absent when there are no more pages.
`hasNextPage`	`boolean`	Whether more pages are available.

`RedactionInput` schema

Field	Type	Description
`redactions`	array of `RedactionEntityDto`	Entities to redact.

`RedactionEntityDto` schema

Field	Type	Description
`pageIndex`	`integer`	Zero-based page index where the entity appears.
`text`	`string`	The matched text. Required.
`label`	`string`	The entity type, for example `EMAIL_ADDRESS` or `PERSON`. Required.
`score`	`number`	Confidence score between 0 and 1.
`quadrilaterals`	array of `QuadrilateralDto`	On-page bounding regions for the entity.

`QuadrilateralDto` schema

All four corners are required. Quadrilaterals can describe rotated or skewed text regions, not only axis-aligned rectangles.

Field	Type	Description
`bottomLeft`	`PointDto`	Bottom-left corner.
`bottomRight`	`PointDto`	Bottom-right corner.
`topRight`	`PointDto`	Top-right corner.
`topLeft`	`PointDto`	Top-left corner.

`PointDto` schema

Field	Type	Description
`x`	`number`	X coordinate in PDF user-space points.
`y`	`number`	Y coordinate in PDF user-space points.

`DetectionResult` schema

Field	Type	Description
`redactions`	array of `RedactionEntityDto`	Detected entities returned by the detection step.

`UserInfoResponse` schema

Field	Type	Description
`userId`	`string`	User identifier.
`email`	`string`	User’s email address.
`fullName`	`string`	User’s full name.
`isActive`	`boolean`	Whether the user account is active.

`JobStatus` enum

Value	Description
`created`	The job is registered. Detection hasn’t started yet.
`detectionInProgress`	Detection is running.
`readyForReview`	Detection is complete. The redaction list is ready for review.
`redactionInProgress`	Redaction is running.
`finished`	Redaction is complete.
`expired`	The job has expired.
`failed`	The job failed.

`JobFileType` enum

Value	Description
`pdf`	The original uploaded PDF.
`fdf`	The FDF file produced by detection.
`redactedPdf`	The redacted PDF, available once the job is `finished`.

`JobSortField` enum

Value	Description
`createdAt`	Sort by creation time.
`updatedAt`	Sort by last update time.

`SortDirection` enum

Value	Description
`asc`	Ascending.
`desc`	Descending.

Job lifecycle​

Endpoints​

Create a job​

List jobs​

Get a job​

Start redaction for a job​

Download a job file​

Schemas​

JobResponse schema​

JobSummaryResponse schema​

JobSummaryResponsePaginatedResponse schema​

RedactionInput schema​

RedactionEntityDto schema​

QuadrilateralDto schema​

PointDto schema​

DetectionResult schema​

UserInfoResponse schema​

JobStatus enum​

JobFileType enum​

JobSortField enum​

SortDirection enum​

Job lifecycle

Endpoints

Create a job

List jobs

Get a job

Start redaction for a job

Download a job file

Schemas

`JobResponse` schema

`JobSummaryResponse` schema

`JobSummaryResponsePaginatedResponse` schema

`RedactionInput` schema

`RedactionEntityDto` schema

`QuadrilateralDto` schema

`PointDto` schema

`DetectionResult` schema

`UserInfoResponse` schema

`JobStatus` enum

`JobFileType` enum

`JobSortField` enum

`SortDirection` enum