API Reference

The Plextera Public API exposes four endpoint groups.

Files

Upload and manage files. A file can be submitted to Document Insights for extraction or referenced in a workflow.

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
• Uploaded files are staged for downstream processing. Use them as inputs for Document Insights or workflow runs rather than as long-term file storage.

Document Insights

Extract structured fields from documents and monitor asynchronous processing.

Document input - use an existing fileId, a public HTTPS url, or direct multipart upload.

Configuration and routing - your workspace’s Document Insights configuration determines which documents match and which fields appear in output.fields. Review the relevant configuration in Plextera to identify the expected output schema and routing mode. If you do not know how to access it, ask your workspace administrator or Plextera. The v1 API does not currently list available configurations or docType values.

Labels - optional string key-value pairs. Custom labels are returned for correlation and do not affect extraction. docType is reserved for configured Document Insights routing. Use the exact value from the relevant configuration in Plextera; if you do not know where to find it, ask your workspace administrator or Plextera. When default routing is available, omit docType but keep any custom labels you need for correlation.

Label limits:

• Up to 50 labels per extraction
• Label keys must be 1-64 characters
• Label values must be 1-512 characters
• Keys and values must be strings and cannot be blank
• docType counts as one label and follows the same limits

For setup steps, examples, and docType guidance, see Document Extraction.

Extraction lifecycle:

QUEUED → PROCESSING → COMPLETED
                    ↘ FAILED
                    ↘ REJECTED

Output - available on GET /document-insights/extractions/{extractionId} once outputAvailable is true. Extractions return a typed fields array with confidence scores and page placement coordinates when available.

List extractions - use GET /document-insights/extractions to review recent extractions and check their status. It supports status, from, to, sortBy, sort, page, size, and deep-object label filters such as labels[docType]=YOUR_CONFIGURED_DOCUMENT_TYPE. Multiple label filters use AND. Use GET /document-insights/extractions/{extractionId} when you need the full output. See Filter by labels for a shell-safe curl example.

List sorting - GET /document-insights/extractions supports sortBy=createdAt|updatedAt|completedAt and sort=asc|desc. Defaults are createdAt and desc.

Timestamps - all timestamps are UTC ISO 8601 strings. createdAt is when Plextera accepted the extraction, updatedAt is the last known state change, and completedAt is present after the extraction reaches COMPLETED, FAILED, or REJECTED.

Extraction errors - failed and rejected extractions include error.code and error.message so clients can handle terminal failures programmatically.

Deletion - DELETE /document-insights/extractions/{extractionId} permanently removes a terminal extraction (COMPLETED, FAILED, REJECTED) and returns 204. Deleting a QUEUED or PROCESSING extraction returns 409 CONFLICT.

Feedback - after reviewing an extraction result, submit corrections per field using POST /document-insights/extractions/{extractionId}/feedback. Include fieldId to target a specific field, or omit it for a general comment. type defaults to ERROR; use INFO for notes that should not mark the extraction as incorrect. Feedback is surfaced to the Document Insights team for extraction quality 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.

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.

Multipart trigger input - POST /workflows/{workflowId}/runs also accepts multipart/form-data for workflows configured to consume form-data, similar to a Studio webhook trigger.

Part names are preserved. If a workflow is configured to read body.document, send a file part named document. If it reads body.attachments, send one or more file parts named attachments. The API reference shows common fields for Try It, but clients can send workflow-specific part names as needed. Workflow part names are independent from Document Insights labels.

Run lifecycle:

PROCESSING → COMPLETED
          ↘ FAILED
          ↘ CLOSED

CLOSED is returned for workflow runs that were closed in Plextera Studio.

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 createdAt to completedAt; omitted until the run is terminal
• computedDurationMs - active processing time reported by Studio, excluding wait states and parallel idle time; it may be omitted from list summaries

Event Subscriptions

Configure webhook endpoints to receive push notifications when document extractions or workflow runs reach terminal states.

Signing secret - Plextera generates the secret. Create returns it once with the new active subscription. List, get, and update never return the secret, PATCH does not accept it, and the Public API has no reveal endpoint.

Filters - optionally restrict workflow events to a specific workflowId. Document Insights events are filtered by the selected event types and do not require a filter object.

List filters and sorting - GET /event-subscriptions supports status, eventType, a creation-time window (from/to), and sorting via sortBy=createdAt|updatedAt and sort=asc|desc (defaults: createdAt, desc).

Event history - GET /events returns immutable product events even when no active subscription matched them. Pass subscriptionId to show only events delivered to one subscription; summary counts are then scoped to that subscription. Use GET /events/{eventId}/deliveries to inspect every automatic delivery and manual resend across subscriptions, or pass subscriptionId to narrow the result.

Delivery details - load one delivery to inspect the event payload and up to 100 recent HTTP attempts. The response indicates whether earlier records were omitted and redacts signatures.

Manual resend - resend a delivery in any state while its subscription is active. The 202 response contains a new one-attempt delivery for the same event.

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

See Event Subscriptions for delivery headers, signature verification, and retry behavior.

Pagination

All list endpoints (GET /document-insights/extractions, GET /workflow-runs, GET /event-subscriptions, GET /events, GET /events/{eventId}/deliveries) use cursor-free, zero-based page parameters:

page must be 0 or greater and size must be between 1 and 100; out-of-range values return 400 INVALID_REQUEST.

Every list response includes a pageInfo object:

1
{
2
  "data": [],
3
  "pageInfo": {
4
    "page": 0,
5
    "size": 50,
6
    "totalItems": 142,
7
    "totalPages": 3
8
  }
9
}

Errors

All error responses use a common envelope:

1
{
2
  "error": {
3
    "code": "VALIDATION_FAILED",
4
    "message": "Request validation failed.",
5
    "requestId": "req_01JY7MFQZ3N8VKJPX2BT6WS0QR",
6
    "retryable": false,
7
    "details": [
8
      {
9
        "field": "labels.priority",
10
        "issue": "Value must not be blank."
11
      }
12
    ]
13
  }
14
}

Error codes

Request IDs

Every response includes an X-Request-Id header with a unique identifier for the request. This ID is also echoed in the requestId field of error responses.

X-Request-Id: req_01JY7MFQZ3N8VKJPX2BT6WS0QR

When reporting issues, always include the X-Request-Id - it allows Plextera to locate the exact request in server logs regardless of timing.