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.

Tags - optional string key-value pairs returned with the extraction. docType is reserved for configured Document Insights routing.

Tag limits:

• Up to 50 tags per extraction
• Tag keys must be 1-64 characters
• Tag values must be 1-512 characters
• Keys and values must be strings and cannot be blank
• docType counts as one tag 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. Use GET /document-insights/extractions/{extractionId} when you need the full output.

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 tags.

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 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 extractions or workflow runs reach terminal states.

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).

Delivery history — GET /event-subscriptions/{subscriptionId}/deliveries returns each delivery’s status (pending, retrying, delivered, failed), attempt count, last HTTP response code, last error, and next scheduled retry. Use it to debug a misbehaving webhook endpoint.

Pausing — set status: paused via PATCH to suspend deliveries without deleting the subscription. Set 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 /event-subscriptions/{subscriptionId}/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": "tags.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.