API Reference

The Plextera Public API exposes four endpoint groups.

Files

Upload and manage files. A file must be uploaded before it can be submitted to a Document Insights job or referenced in a workflow.

EndpointDescription
POST /filesUpload a file. Returns the assigned fileId.
GET /files/{fileId}Retrieve file metadata.
GET /files/{fileId}/downloadDownload raw file content.

Constraints:

  • Maximum file size: 50 MB
  • Supported: PDF, JPEG, PNG, TIFF, WebP, DOCX, XLSX, PPTX, plain text, CSV, HTML, archives, audio, video
  • Rejected: executable and script files

Document Insights

Create and monitor asynchronous document processing jobs against a configured hub.

EndpointDescription
POST /document-insights/jobs/extractSubmit a document for structured field extraction.
GET /document-insights/jobsList jobs, optionally filtered by status.
GET /document-insights/jobs/{jobId}Get job state and output.
POST /document-insights/jobs/{jobId}/feedbackSubmit a field correction or comment.

Document input — jobs accept either a previously uploaded file (fileId) or a publicly accessible URL.

Hub routing — jobs are routed to a Document Insights hub for processing. Specify a hubId explicitly, or let Plextera determine the hub automatically using:

  • metadata key-value pairs included in the request
  • Smart classification (if enabled for the organization)
  • The organization’s default hub

Extract job limits:

  • hubId is optional. When provided, it must be a valid 24-character hexadecimal id for an enabled hub in your organization. Empty or unknown hub ids are rejected.
  • metadata is optional and must contain string key-value pairs only.
  • metadata keys and values must be non-empty after trimming whitespace.
  • metadata supports up to 50 entries, 64 characters per key, and 512 characters per value.

Job lifecycle:

QUEUED → PROCESSING → COMPLETED
                    ↘ FAILED
                    ↘ REJECTED
StatusMeaning
QUEUEDJob accepted, not yet started.
PROCESSINGActively being processed.
COMPLETEDOutput is ready; outputAvailable: true.
FAILEDProcessing failed due to an internal error.
REJECTEDDocument rejected before or during validation. Reasons include: broken, empty, or oversized file; unsupported language; or duplicate document (the same document cannot be submitted twice).

Output — available on GET /document-insights/jobs/{jobId} once outputAvailable is true. Extract jobs return an ExtractionOutput with a typed fields array, confidence scores, and page placement coordinates.

Feedback — after reviewing an extraction result, submit corrections per field using POST /document-insights/jobs/{jobId}/feedback. Include fieldId to target a specific field, or omit it for a general comment. Feedback is surfaced to the hub configuration team for model improvement.

Feedback messages are required and limited to 1024 characters.

Workflows

Trigger and monitor workflow runs. Workflows are configured in Plextera Studio and can include Document Insights steps, data transformation, and custom processing logic.

EndpointDescription
POST /workflows/{workflowId}/runsTrigger a new workflow run.
GET /workflow-runsList runs, optionally filtered by status or workflow.
GET /workflow-runs/{runId}Get detailed run state, step outputs, and nested runs.

Trigger payload — the request body is passed to the workflow as its trigger input. Any valid JSON is accepted; the expected structure depends on the workflow’s trigger configuration. Omit the body entirely if the workflow requires no input.

Run lifecycle:

QUEUED → PROCESSING → COMPLETED
                    ↘ FAILED

Step output — GET /workflow-runs/{runId} returns step-level status and output for each step. Steps that start nested sub-workflows expose those runs in nestedRuns. Use GET /workflow-runs/{runId} with a nested run’s id to load full nested run details.

Duration fields:

  • durationMs — wall-clock time from startedAt to completedAt
  • computedDurationMs — active processing time, excluding wait states and parallel idle time

Event Subscriptions

Configure webhook endpoints to receive push notifications when Document Insights jobs or workflow runs reach terminal states.

EndpointDescription
POST /event-subscriptionsCreate a subscription.
GET /event-subscriptionsList subscriptions.
GET /event-subscriptions/{subscriptionId}Get a subscription.
PATCH /event-subscriptions/{subscriptionId}Update endpoint, event types, filters, secret, or status.
DELETE /event-subscriptions/{subscriptionId}Delete a subscription.

Filters — optionally restrict a subscription to events from a specific workflowId or Document Insights operation (extract).

Pausing — set status: paused via PATCH to suspend deliveries without deleting the subscription. Set back to active to resume.

Pagination — all list endpoints use zero-based page and size parameters. Default page size is 50, maximum is 100.

See Events for delivery headers, signature verification, and retry behavior.