Welcome to AquaCloud
This is the documentation of the API developed by AquaCloud, intended for developers.
Registration and authentication is mandatory when using the API.
The AquaCloud API adheres to the RESTful principles. The API is read-only and uses GET for data retrieval.
Data Sharing & Governance
AquaCloud is all about creating value by applying industry data. By sharing industry data, AquaCloud can save months of work trying to access and compile data for projects and trials, increasing the time for developing findings and new solutions.
As a non-profit organisation, our mission is to support the aquaculture industry by providing high-quality data and insights. While we are committed to open collaboration, we reserve the right to charge for datasets to ensure the sustainability of our operations, maintain data quality, and continue delivering valuable services to the industry.
Rules of Engagement
All applications for data are vetted by a steering committee of fish farmers. They work with us in AquaCloud to ensure that data is used to create value through insights and new services and that the value applies to the industry. Last, the steering committee is an extra security to ensure all data sharing follows the well-defined data sharing governance.
Authentication
The Aquacloud API uses OAuth 2.0 / OpenID Connect authentication through Keycloak. All API requests require a valid access token.
Your username and password carry many privileges, se be sure to keep them secure. Do not share your API token in public accessible areas such as GitHub, client-side code etc.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
Aquacloud API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Aquacloud servers.
| CODE | NAME | DESCRIPTION |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized | No valid token provided. |
| 403 | Forbidden | The token doesn’t have permissions to perform the request. |
| 404 | Not Found | The requested resource doesn’t exist. |
| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 | Service Unavailable | Something is wrong on AquaClouds end. |
In the case of 5xx errors contact support at support@aquacloud.ai, please include the full request ID from the response headers (e.g., X-Request-Id).
Metadata
The AquaCloud API includes metadata fields in most responses:
api_version: Indicates the version of the API used for the response. This helps ensure compatibility and allows clients to handle changes between API versions.
request_id: A unique identifier for each API request, useful for tracking, debugging, and support. Include this ID when contacting support about specific requests.
exclude_self: A flag indicating whether the response excludes data related to the requesting user or entity. Useful for filtering out the caller’s own data in queries.
Pagination
The AquaCloud API supports pagination for endpoints that return lists of data. Pagination helps you efficiently retrieve large datasets in smaller chunks.
limit:
The maximum number of records to return in a single response. Use this to control page size (e.g., limit=10 returns up to 10 results).
offset:
The starting position in the dataset. Use this to skip a number of records (e.g., offset=20 skips the first 20 results).
has_more:
A boolean field in the response indicating whether more results are available beyond the current page. If has_more is true, you can request the next page by increasing the offset.
Request IDs
Each response contains a unique request_id header. Always include this when reporting issues—it allows support to quickly locate the exact request in system logs.
Versioning
The AquaCloud API is versioned to ensure backward compatibility and provide a clear upgrade path. API versions are reflected in the endpoint paths (e.g., /v2/, /v3/).
Breaking changes are introduced only in new versions, while existing versions remain stable. This allows developers to migrate at their own pace.
Support
Need help getting started?
- Swagger API Docs: Interactive testing at api.aquacloud.ai
- Support: support@aquacloud.ai