Endpoints

AquaMeter AI exposes two REST endpoints for meter image processing: an asynchronous default and a synchronous alternative.

POST /api/meter-reading (Asynchronous)

POSThttps://www.aquameter.site/api/meter-reading

Submits a water meter image for AI analysis. The default endpoint is asynchronous: it acknowledges the request immediately with a reference_id, then queues the image for processing. The reading is delivered to your webhook endpoint as a reading.completed or reading.failed event, usually within 1–3 seconds. There is no GET endpoint to poll — you must configure a webhook on the Webhooks page first.

POST /api/meter-reading/sync (Synchronous)

POSThttps://www.aquameter.site/api/meter-reading/sync

The synchronous alternative. This endpoint blocks the request until the AI processing is complete and returns the reading directly in the HTTP response. Webhooks will not be dispatched for this endpoint. Use this if your client prefers to wait for the result instead of handling webhooks.

Properties

MethodPOST
Content-Typemultipart/form-data (set automatically by your HTTP client)
AuthenticationBearer token in Authorization header
ProcessingAsynchronous — ack returned inline, reading delivered via webhook
Ack latencyTypically under 200 ms
Reading latency1–3 seconds end-to-end (ack + webhook delivery)
Max image size10 MB

What happens on each request

1

API key validated

Your Bearer token is checked against active keys. Invalid or inactive keys return 422.

2

Subscription checked

An active subscription is required. None or expired returns 422.

3

Usage limit enforced

Monthly request count is compared against the plan limit. Over limit returns 422.

4

Image validated

Multipart image field is checked for presence and size (max 10 MB).

5

Acknowledgement sent

A reference_id is generated and the JSON ack is returned to your client.

6

Job enqueued

Image upload + AI processing is dispatched to a background queue.

7

AI extracts reading

The image is resized, converted to JPEG, and sent to the vision model. Failures fall back to a secondary model.

8

Reading persisted

On success, a Reading row is inserted and the Meter row is marked completed. On failure the Meter is marked failed.

9

Usage recorded

The api_usage row for the current month is incremented and last_used_at is updated on the key.

10

Webhook delivered

reading.completed (or reading.failed) is signed with HMAC-SHA256 and POSTed to your endpoint. For synchronous requests, steps 5-6 and 10 are skipped and the data is returned directly in the response.

Example

curl
curl -X POST https://www.aquameter.site/api/meter-reading \
  -H "Authorization: Bearer aqm_live_YOUR_API_KEY" \
  -F "image=@/path/to/meter.jpg"
AuthenticationRequest