Aquabyte Biomass API

openapi: 3.2.0
info:
  title: Aquabyte API Documentation Biomass 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: biomass
  description: Biomass APIs
paths:
  /biomass:
    get:
      tags:
      - biomass
      summary: Biomass data for a pen
      operationId: get_biomass_daily_biomass_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: fromDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: from date. Default is 7 days before toDate
        description: from date. Default is 7 days before toDate
      - name: toDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: to date (inclusive). Default is today
        description: to date (inclusive). Default is today
      - name: bucketSize
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: weightDist bucket size. Default 1000g
          default: 1000
        description: weightDist bucket size. Default 1000g
      - 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__2'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /biomass/harvestReport:
    get:
      tags:
      - biomass
      summary: Biomass harvest reports in the date range (by slaughter start)
      description: Returns main reports. If there is no main report, returns the latest one.
      operationId: get_biomass_harvest_report_biomass_harvestReport_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: fromDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: from date. Default is 7 days before toDate
        description: from date. Default is 7 days before toDate
      - name: toDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: to date (inclusive). Default is today
        description: to date (inclusive). Default is today
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiomassHarvestReportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BiomassHarvestReportResponse:
      properties:
        reports:
          items:
            $ref: '#/components/schemas/BiomassHarvestReport'
          type: array
      type: object
      required:
      - reports
      title: BiomassHarvestReportResponse
    WeightDistModel:
      properties:
        interval:
          items:
            type: number
          type: array
        distribution:
          items:
            type: number
          type: array
      type: object
      required:
      - interval
      - distribution
      title: WeightDistModel
    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
    BiomassDailyModel:
      properties:
        penId:
          type: string
        date:
          type: string
          format: date
        sampleSize:
          anyOf:
          - type: number
          - type: 'null'
          description: Number of samples used for avgWeight
        avgWeight:
          anyOf:
          - type: number
          - type: 'null'
          description: Average weight in grams
        kFactor:
          anyOf:
          - type: number
          - type: 'null'
        cv:
          anyOf:
          - type: number
          - type: 'null'
        weightDist:
          $ref: '#/components/schemas/WeightDistModel'
      type: object
      required:
      - penId
      - date
      - sampleSize
      - avgWeight
      - kFactor
      - cv
      - weightDist
      title: BiomassDailyModel
    BiomassHarvestReport:
      properties:
        penId:
          type: string
        mainReport:
          type: boolean
          description: If this is a main report
        asOfDate:
          type: string
          format: date
          description: Latest date of data used in the report (primarily for forecasting).
        lastFeedingDate:
          type: string
          format: date
          description: Last feeding date.
        slaughterStartDate:
          type: string
          format: date
          description: Slaughter start date.
        slaughterEndDate:
          type: string
          format: date
          description: Slaughter end date.
        temperature:
          type: number
          description: Temperature.
        lossFactor:
          type: number
          description: Total loss factor from packing process (excludes starvation).
        packingMethod:
          anyOf:
          - type: string
          - type: 'null'
          description: Packing method (HOG, WFE, or null if custom loss).
        fishType:
          anyOf:
          - type: string
          - type: 'null'
          description: Fish type. Null for reports created prior to 2025-08-14.
        measurementCount:
          type: integer
          description: Total number of fish measured for the report.
        coefficientOfVariation:
          type: number
          description: Coefficient of variation.
        avgPackedWeightGrams:
          type: number
          description: Average packed weight in grams.
        avgRoundWeightGrams:
          type: number
          description: Average round weight in grams of fish on last feeding date.
        superiorRate:
          type: number
          description: Superior rate.
        packedWeightDistribution:
          additionalProperties:
            type: number
          type: object
          description: Packed weight distribution. Keys express intervals in kg ('4-5' for 4kg to 5kg), values are expressed in percentages (15 for 15%).
        roundWeightDistribution:
          additionalProperties:
            type: number
          type: object
          description: Round weight distribution. Keys express intervals in kg ('4-5' for 4kg to 5kg), values are expressed in percentages (15 for 15%).
        createdAt:
          type: string
          format: date-time
      type: object
      required:
      - penId
      - mainReport
      - asOfDate
      - lastFeedingDate
      - slaughterStartDate
      - slaughterEndDate
      - temperature
      - lossFactor
      - packingMethod
      - fishType
      - measurementCount
      - coefficientOfVariation
      - avgPackedWeightGrams
      - avgRoundWeightGrams
      - superiorRate
      - packedWeightDistribution
      - roundWeightDistribution
      - createdAt
      title: BiomassHarvestReport
    aqua_api__paginator__append_next_token___locals___Wrapped__2:
      properties:
        biomass:
          items:
            $ref: '#/components/schemas/BiomassDailyModel'
          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:
      - biomass
      title: Wrapped