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:

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 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:

{
  "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"
  }
}

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:

{
  "fileUrl": "https://storage.example.com/files/abc123.pdf",
  "jobId": "d0b3c7fc-4911-440b-9e4d-fefca935bc0e"
}

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:

{
  "isReady": false
}

When ready — inline result:

{
  "isReady": true,
  "result": {
    "your": "extraction output here"
  }
}

When ready — result at a URL:

{
  "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.