Aquabyte Environmental API

openapi: 3.2.0
info:
  title: Aquabyte API Documentation Environmental API
  description: "\n# Aquabyte Public API\n\nTo use our API you must be issued an API key.\n\nInstructions: For all HTTPS requests you will need to pass in your API key as part of the header:\n`apikey: {API_KEY}`\n\nOur base url is https://api.aquabyte.ai/v3/\n\nRequests are limited to 1000 requests/hour\n\n\n# What's new in v3.1\n\nWith v3.1, we have added new APIs to support bulk fetching. One of the\nmain use case is for users to download Aquabyte data into their own database.\nThe new API allows us to download all pens with available data in a single call.\nFor example, to fetch biomass data for all pens, you can use the following API call:\n\n```\nGET \"https://api.aquabyte.ai/v3/biomass?penId=all&fromDate=2026-01-01&toDate=2026-01-02\"\n```\n\nYou can switch to v3.1 API simply by changing the URL from this pattern\n`GET /pens/{penId}/biomass` to this pattern `GET /biomass?penId={penId}`. Similar\npattern is used for other data - environmental, lice, welfare and behaviour.\n\nSince v3.1 supports everything in v3.0. We recommend switching to v3.1 as soon as possible.\nv3.0 support continues during the transition.\n\n\n## Result pagination\n\nCurrently, Aquabyte Public API caps the result set up to 10,000 records.\nIf the result set has more data than the limit, they will be returned in batches.\nIn this case, the response will contain a \"nextToken\". For example:\n\n```\nGET \"https://api.aquabyte.ai/v3/biomass?penId=all&fromDate=2025-01-01&toDate=2025-12-31\"\n\n\nIt returns\n\n{\n  \"biomass\": [\n    ... up to limit number of records ...\n  ]\n  \"nextToken\": \"(A_TOKEN)\"\n}\n```\n\nTo fetch the next batch of data, repeat the request and add the \"nextToken\" to the query parameters.\n\n```\nGET \"https://api.aquabyte.ai/v3/biomass?penId=all&fromDate=2025-01-01&toDate=2025-12-31&nextToken=(A_TOKEN)\"\n```\n\nRepeating the request until \"nextToken\" is not present in the response.\nThis indicates that you have fetched all data.\n\n"
  version: v3.1
servers:
- url: /v3
- url: https://api.aquabyte.ai/v3
  description: Aquabyte API Server
tags:
- name: Environmental
paths:
  /environmental:
    get:
      summary: Historical environmental data
      operationId: get_environmental_environmental_get
      parameters:
      - name: penId
        in: query
        required: true
        schema:
          type: string
          description: penId to query. Use "all" to query all pens
        description: penId to query. Use "all" to query all pens
      - name: fromTime
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: from time. Default is 1 days ago
        description: from time. Default is 1 days ago
      - name: toTime
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: to time (exclusive). Default is today
        description: to time (exclusive). Default is today
      - name: period
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Period15mEnum'
          - type: 'null'
          description: aggregation period of the metric. Default is daily
          default: D
        description: aggregation period of the metric. Default is daily
      - name: nextToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: (optional) token to fetch the next batch of result
        description: (optional) token to fetch the next batch of result
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/aqua_api__paginator__append_next_token___locals___Wrapped__1'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Environmental
  /environmental/latest:
    get:
      summary: Latest environmental data
      operationId: get_environmental_latest_all_pens_environmental_latest_get
      parameters:
      - name: penId
        in: query
        required: true
        schema:
          type: string
          description: penId to query. Use "all" to query all pens
        description: penId to query. Use "all" to query all pens
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEnvironmentalLiveAllResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Environmental
components:
  schemas:
    EnvironmentalDataLive:
      properties:
        penId:
          anyOf:
          - type: string
          - type: 'null'
        time:
          type: string
          format: date-time
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          description: temperature (celcius)
        cameraDepth:
          anyOf:
          - type: number
          - type: 'null'
          description: camera depth (meters)
        oxygenPct:
          anyOf:
          - type: number
          - type: 'null'
          description: Dissolved Oxygen Saturation (%)
        salinity:
          anyOf:
          - type: number
          - type: 'null'
          description: Salinity parts per thousand (ppt)
      type: object
      required:
      - time
      title: EnvironmentalDataLive
    Period15mEnum:
      type: string
      enum:
      - h
      - D
      - 15min
      title: Period15mEnum
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input: {}
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GetEnvironmentalLiveAllResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/EnvironmentalDataLive'
          type: array
      type: object
      required:
      - data
      title: GetEnvironmentalLiveAllResponse
    EnvironmentalDataPoint:
      properties:
        penId:
          type: string
        fromTime:
          type: string
          format: date-time
        toTime:
          type: string
          format: date-time
        temperatureAvg:
          anyOf:
          - type: number
          - type: 'null'
          description: Average temperature (celcius)
        cameraDepthAvg:
          anyOf:
          - type: number
          - type: 'null'
          description: camera depth (meters)
        cameraDepthMin:
          anyOf:
          - type: number
          - type: 'null'
          description: min camera depth (meters)
        cameraDepthMax:
          anyOf:
          - type: number
          - type: 'null'
          description: max camera depth (meters)
        oxygenPct:
          anyOf:
          - type: number
          - type: 'null'
          description: Dissolved Oxygen Saturation (%)
        salinity:
          anyOf:
          - type: number
          - type: 'null'
          description: Salinity parts per thousand (ppt)
        fishDensity:
          anyOf:
          - type: number
          - type: 'null'
          description: Fish density (0 to 1)
      type: object
      required:
      - penId
      - fromTime
      - toTime
      title: EnvironmentalDataPoint
    aqua_api__paginator__append_next_token___locals___Wrapped__1:
      properties:
        penId:
          anyOf:
          - type: string
          - type: 'null'
          description: unused
        fromTime:
          type: string
          format: date-time
          description: from time
        toTime:
          type: string
          format: date-time
          description: to time
        data:
          items:
            $ref: '#/components/schemas/EnvironmentalDataPoint'
          type: array
        nextToken:
          anyOf:
          - type: string
          - type: 'null'
          description: If this is null, the result set is complete. If not null, fetch the next batch of result by passing this token to the next request.
      type: object
      required:
      - data
      title: Wrapped