> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server. # Client Integration Guide This guide covers the technical contracts your application must satisfy to integrate with the Fluxx platform. There are two distinct integration points, and you may need one or both depending on your use case: | You Must Provide | If you... | | --------------------------------------------------------------- | --------------------------------------------------- | | **A delivery endpoint** that accepts status messages from Fluxx | ...want to receive event notifications from Fluxx | | **An extractor endpoint** where Fluxx will send extraction jobs | ...want Fluxx to provide your files to an extractor | --- ## Registration Before Fluxx can communicate with your application, it must be registered. Registration is where you configure everything Fluxx needs to know about your application: your delivery preferences, your extractor endpoints, and which processing steps Fluxx will perform on your files. Every step after upload is optional — including classification, splitting, extraction, and delivery of results. What is not optional is the upload itself, since that is how files enter the system. File criteria such as maximum file size and allowed extensions are also set at registration time. You will provide at registration time: * A unique **client application name** * A **`deliveryUrl`** (if receiving event notifications via HTTP) * An **`extractionUrl`** (if operating an extractor) * A **`pollingUrl`** (if operating an extractor — see [Extractor Endpoint](#extractor-endpoint) below) Registration is handled through the Fluxx onboarding process. Once your registration is complete, you will receive a `clientApplicationId` and related identifiers that you should retain. --- ## Delivery Endpoint Fluxx's Postal Service routes file processing event notifications — such as extraction completion or processing failures — to your registered application. When an event is ready for your application, the Postal Service makes an HTTP POST to your registered `deliveryUrl`. ### What You Must Expose An HTTP endpoint that: * Accepts **`POST`** requests * Accepts a **`Content-Type: application/json`** body * Returns **`200 OK`** to confirm receipt — this is the only accepted success code * Is **idempotent** — the same message may be delivered more than once due to retries; your handler must tolerate this safely ### Message Payload The Postal Service forwards the message exactly as it was published — it does not modify or transform the content. The envelope shape is something similar to: ```json { "messageId": "d0b3c7fc-4911-440b-9e4d-fefca935bc0e", "timestamp": "2025-08-01T11:00:00Z", "client": "your-client-name", "payload": { "fileId": "0d799806-8289-4a17-b0c1-bdf5dee6d662", "status": "complete", "location": "https://fluxx-results/493aa1b5-4c26-4f23-b1cb-8ccf398fe5ee/0d799806-8289-4a17-b0c1-bdf5dee6d662.json" } } ``` | Field | Description | | ----------- | -------------------------------------------------------------------- | | `messageId` | Unique identifier for this message. Use this for idempotency checks. | | `timestamp` | ISO 8601 timestamp of when the event was generated. | | `client` | The client name this message was routed to. | | `payload` | Event-specific data. Shape varies by event type. | ### Failure and Retry Behavior Any response other than `200` — including `4xx`, `5xx`, timeouts, or connection failures — will be treated as a delivery failure. Fluxx will retry with exponential backoff up to a maximum interval, then continue retrying at that interval indefinitely. There is no automatic abandonment — if your endpoint recovers, delivery will resume from the point it started failing. If delivery to an endpoint needs to be permanently stopped, that requires manual intervention on the Fluxx side. If your endpoint needs to temporarily slow down incoming deliveries, returning `429 Too Many Requests` is the conventional signal — but any non-`200` response has the same effect: Fluxx will back off and retry. So a `500` on a processing error works just as well. Because retries will occur, your endpoint **must** handle duplicate deliveries without side effects. Use `messageId` as your idempotency key. ### Delivery Endpoint Checklist * [ ] Endpoint accepts `POST` requests with a JSON body * [ ] Endpoint returns `200 OK` on successful receipt * [ ] Duplicate deliveries of the same `messageId` are handled safely * [ ] Endpoint is reachable from the Fluxx network --- ## Extractor Endpoint When a file is uploaded to Fluxx, it goes through a pipeline: files are scanned, optionally classified, and — if the document contains multiple embedded forms — split into sub-documents along form boundaries. If your registration includes an extractor, Fluxx will submit each of those sub-documents to your registered `extractionUrl` for processing. Once your extractor signals completion, Fluxx picks up the results and notifies your application via the delivery endpoint. > **Virus scanning:** All uploaded files are scanned before processing continues. If a file fails the scan it is deleted and not processed further — your application will be notified via the delivery endpoint. Files that pass are acknowledged the same way — your application will receive a delivery notification confirming the file was accepted. ### Job Submission Fluxx sends a `POST` to your registered `extractionUrl` when a file is ready for processing. **Request body:** ```json { "fileUrl": "https://storage.example.com/files/abc123.pdf", "jobId": "d0b3c7fc-4911-440b-9e4d-fefca935bc0e" } ``` | Field | Description | | --------- | ------------------------------------------------------------------------ | | `fileUrl` | URL to the file to be processed. Download it from here. | | `jobId` | UUID assigned by Fluxx. Treat it as opaque; include it in all responses. | **Required response:** `HTTP 201 Created`. We ignore the response body. Any other status code is treated as a submission failure — the job will be marked as failed and no polling will occur. ### Polling for Results After submitting a job, Fluxx will periodically call your registered `pollingUrl`: ``` GET {pollingUrl}/{jobId} ``` **When not yet ready:** ```json { "isReady": false } ``` **When ready — inline result:** ```json { "isReady": true, "result": { "your": "extraction output here" } } ``` **When ready — result at a URL:** ```json { "isReady": true, "resultUrl": "https://your-service.net/results/abc123.json" } ``` Polling rules: * `isReady` is **always required** * When `isReady: true`, include **either** `result` or `resultUrl` — not both * When `isReady: false`, all other fields are ignored **Polling exhaustion:** Fluxx will poll up to a configured maximum number of attempts. If that limit is reached before `isReady: true` is returned, the job is marked as permanently failed. Unlike delivery retries, polling does not continue indefinitely — design your extractor to complete within a reasonable window. --- ### Extractor Endpoint Checklist * [ ] `extractionUrl` accepts `POST` with `{ fileUrl, jobId }` and returns `201 Created` * [ ] Jobs are tracked by `jobId` so status can be reported correctly * [ ] `GET {pollingUrl}/{jobId}` returns `{ isReady }` with the correct shape * [ ] Your endpoint is reachable from the Fluxx network --- ## Security Notes ### Service-to-Service Authentication Fluxx is a service for services — there are no user-facing endpoints. All communication between Fluxx and your application uses standard service-to-service authentication via Azure Managed Identity. Your application should be configured accordingly. If you are using the internal application framework and deploying to the shared landing zone, this is largely handled for you. ### Prompt and Model Safety (Extractor Operators) Fluxx delivers file bytes and metadata to your `extractionUrl`. **You are fully responsible for how those bytes are interpreted and used within your model or processing logic.** This includes: * Hardening prompt templates against injection via extracted content * Ensuring OCR, PDF, or image parsing does not introduce unexpected instructions into LLM inputs * Ensuring the model only performs expected operations regardless of file structure Prompt injection and output misuse risks reside entirely within your code and model-handling logic. Fluxx makes no guarantees about the content of submitted files. ### Network Requirements All URLs you register (`deliveryUrl`, `extractionUrl`, `pollingUrl`) must be reachable from Fluxx's network. Firewall rules, VNet peering, and egress configuration are your responsibility.