Getting started

To use the API a user account is necessary

Create account

1. Create an account (or get invited by an admin).
2. Use the presigned URLs or credentials to access resources.

tip

Explore and test all API endpoints interactively at api.aquacloud.ai - Try queries, test authentication, and see responses.

Obtain credentials

All endpoints are protected and require a Bearer token obtained via the OAuth2 Password Grant.

To authenticate with the AquaCloud API, request an access token by making a POST request to the /token endpoint:

Token request

curl -X POST https://api.aquacloud.ai/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=<your_username>" \
  -d "password=<your_password>"

Token response

{
  "access_token": "<access_token>",
  "expires_in": 3600,
  "refresh_expires_in": 1800,
  "refresh_token": "......",
  "token_type": "Bearer",
  "id_token": "......",
  "not-before-policy": 0,
  "session_state": "...",
  "scope": "openid email profile"
}

First request

Use the <access_token> from the /token response body in the request

Request

curl -X 'GET' \
  'https://api.aquacloud.ai/v3/common/farmers-per-po' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Response

[
    {
        "production_area_id": 2,
        "number_of_farmers": 2
    },
    {
        "production_area_id": 3,
        "number_of_farmers": 4
    },
    {
        "production_area_id": 4,
        "number_of_farmers": 5
    },
    {
        "production_area_id": 5,
        "number_of_farmers": 4
    },
    {
        "production_area_id": 6,
        "number_of_farmers": 6
    },
    {
        "production_area_id": 7,
        "number_of_farmers": 3
    },
    {
        "production_area_id": 8,
        "number_of_farmers": 6
    },
    {
        "production_area_id": 9,
        "number_of_farmers": 3
    },
    {
        "production_area_id": 10,
        "number_of_farmers": 5
    },
    {
        "production_area_id": 11,
        "number_of_farmers": 2
    },
    {
        "production_area_id": 12,
        "number_of_farmers": 4
    },
    {
        "production_area_id": 13,
        "number_of_farmers": 2
    }
]

Troubleshooting first call

Common issues

401 Unauthorized Token missing/expired/invalid. Ensure you include Authorization: Bearer <access_token> and there’s no whitespace or quotes around the token.

403 Forbidden Your user or client lacks access to this resource. Verify your account permissions and any data-access approvals.

404 Not Found Endpoint path or version is incorrect. Double-check https://api.aquacloud.ai/v3/...

429 Too Many Requests You’ve hit a rate limit. Use exponential backoff and respect Retry-After if present.

5xx Server Error Temporary issue. Retry with backoff; include your X-Request-Id if contacting support.

tip

When debugging, log the full request ID from the response headers (e.g., X-Request-Id) and include it in support tickets.