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": "https://api.hub.akuasense.com/problems/ambiguous-company",
  "title": "Ambiguous company",
  "status": 400,
  "detail": "Your key covers several companies; set the X-Company-ID header.",
  "instance": "/v1/modules"
}

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 nextCursor; pass it in the cursor parameter for the next page. limit controls the page size.

# 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=eyJpZCI6..." \
  -H "x-api-key: YOUR_API_KEY"

When nextCursor is null, you’ve reached the end.

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.