Use the API

Keys

Create and revoke API keys from your profile (Business plan). Keys are shown once at creation; send them with every request in the X-API-Key header.

What is available today

API keys drive the same endpoints the app uses. Two flows are documented here: coordinate transformation under /api/v1/axis, and quality analysis under /api/v1/quality-analysis. Plan limits (daily sessions, file sizes) apply to API traffic exactly as they do in the app.

Coordinate transformation

POST /api/v1/axis/transform with your source and target CRS and coordinates, and the X-API-Key header. The response mirrors what the Axis workspace shows, including the transformation path. CRS search and frame queries live under the same prefix.

Quality analysis round trip

1. Upload observation files: POST /api/v1/quality-analysis/upload as multipart form data, field name "files" (up to 20 per request), with the X-API-Key header. The response returns records for each uploaded file.
2. Create the analysis: POST /api/v1/quality-analysis/tasks with JSON {"config": {"tool": "<mode id>"}, "files": [<records from step 1>]}. Mode ids: "fast" for Fast Mode, "flash" for Flash Mode, "full" for Full Mode, "teqc" for TEQC Mode.
3. Poll GET /api/v1/quality-analysis/tasks/{taskId} until status is completed; the same response then carries the full results object.
4. Fetch the quality report as PDF via GET /api/v1/quality-analysis/tasks/{taskId}/report.pdf.

Webhooks

Instead of polling, register a webhook and PosFlow calls you when a job finishes. Manage webhooks under /api/v1/webhooks: POST to create (JSON body with "url", "events", and optional "secret" and "description"), GET to list, DELETE /api/v1/webhooks/{id} to remove, and POST /api/v1/webhooks/{id}/test to send a test delivery. The URL must be public https; private and internal addresses are rejected.

Webhook events and payload

Three events fire today: "analysis.completed" when a quality analysis or processing task finishes successfully, and "processing.completed" / "processing.failed" when a conversion job reaches its terminal state. Each delivery is a JSON POST with "event", "timestamp", a unique "id", and a "data" object carrying the job identifier and results. The event name is repeated in the X-Webhook-Event header.

Verifying and reliability

If you set a secret, every delivery carries an HMAC-SHA256 signature of the raw body in the X-POSFLOW-Signature header ("sha256=<hex>"; X-Webhook-Signature holds the bare hex). Compute the HMAC of the received body with your secret and compare. Failed deliveries are retried up to 3 times with backoff; a webhook that keeps failing is disabled after 10 consecutive failed events, so make your receiver return a 2xx quickly and do the work asynchronously.

Good citizenship

Requests are rate limited by plan. Batch what you can, back off on errors, and contact support before sustained high-volume use so we can plan capacity with you.