REST API — Overview

The /v1 REST API exposes your Akuasense data as JSON. This page describes the conventions common to every endpoint. For per-endpoint details, see the API Reference.

Base URL & versioning

https://api.hub.akuasense.com/v1

The /v1 segment is the major version. Backward-compatible additions happen within /v1; a breaking change would yield /v2. See Versioning.

Authentication

API key in the x-api-key header. Multi-company via X-Company-ID. Details and scopes: Authentication.

Date format and units

• Dates / times: ISO 8601 in UTC (e.g. 2026-06-14T09:30:00Z).
• Measurements: every numeric value carries its unit (never an implicit unit). Reference data (crops, textures…) is returned as { code, label }, where label is localizable via the lang parameter (default en).

Errors (RFC 9457)

Errors follow the Problem Details (RFC 9457) standard: an application/problem+json JSON body.

{
  "type": "about:blank",
  "title": "ambiguous_company",
  "status": 400,
  "code": "ambiguous_company",
  "detail": "cette clé couvre plusieurs sociétés (7, 12) — précisez l'en-tête X-Company-ID"
}

The field to test in your code is code: it is stable, and the reference lists it route by route. detail speaks to whoever is debugging — it may be reworded, and is written in French today. Domain refusals carry an uppercase code (MISSING_DURATION, EFFECTIVE_FROM_IN_FUTURE…), transport ones a lowercase code (invalid_id, forbidden_resource, insufficient_scope…).

Status	Common meaning
400	Invalid request (e.g. ambiguous_company)
401	Missing or invalid key
403	Insufficient scope or role
404	Resource not found (or outside your company)
409	Conflict (e.g. idempotency)
429	Quota exceeded

Cursor pagination

Lists are paginated by cursor (not by page number). The response contains a next_cursor; pass it back unchanged in the cursor parameter for the next page. limit controls the page size: 50 by default, 200 at most.

# First page
curl "https://api.hub.akuasense.com/v1/modules?limit=50" \
  -H "x-api-key: YOUR_API_KEY"

# Next page
curl "https://api.hub.akuasense.com/v1/modules?limit=50&cursor=NTA" \
  -H "x-api-key: YOUR_API_KEY"

When next_cursor is null, you’ve reached the end. The cursor is opaque: do not build one, and read nothing into it — just hand it back.

Quotas

Limit	Value
Per minute	60 requests
Per day	10,000 requests

Beyond that, the API returns 429. Space out your calls and cache reference data.

Information

Writes (POST/PUT/PATCH) accept an Idempotency-Key header: re-sending the same request with the same key does not create a duplicate. Recommended for automations.

Write idempotency

Provide a unique Idempotency-Key per logical operation. On a retry (network, re-send), the API recognizes the key and returns the original result instead of duplicating.