swagger: '2.0'
info:
  description: >-
    Public product API.


    This API uses Bearer token authentication.

    To retrieve an access token perform an OAuth2 password grant request to:

    `https://auth.carboncloud.com/realms/prod/protocol/openid-connect/token`


    With the following urlencoded parameters in the body:

    - client_id: `carboncloud`

    - grant_type: `password`

    - username: `<your username>`

    - password: `<your password>`


    Pass in the access token to endpoint requests in a header like
    `Authorization: Bearer <access_token>`.


    Set the `x-request-id` header to a random value in each request. Include the
    header value from relevant requests in trouble reports to aid
    troubleshooting.
  title: Product API
  contact: {}
  version: v1
host: api.carboncloud.com
basePath: /v1
paths:
  /footprints/{product-id}:
    get:
      description: Get footprint by product ID.
      produces:
        - application/json
      tags:
        - Products
      summary: Get specific product footprint.
      parameters:
        - type: string
          description: Product (UUID) ID.
          name: product-id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/BasicFootprint'
        '204':
          description: No Content
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /footprints/{product-id}/flag:
    get:
      description: >-
        Get forest, land and agriculture emission breakdown of a specific
        product.
      produces:
        - application/json
      tags:
        - Products
      summary: Get FLAG breakdown of specific product.
      parameters:
        - type: string
          description: Product (UUID) ID.
          name: product-id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/FlagFootprint'
        '204':
          description: No Content
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /groups:
    get:
      description: >-
        List available groups.

        Every products belongs to exactly one group but multiple groups can be
        allowed to read a single product.

        The response IDs can be used in other endpoints to narrow down results.
      produces:
        - application/json
      tags:
        - Groups
      summary: List groups.
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /products:
    get:
      description: List products available to your organisation.
      produces:
        - application/json
      tags:
        - Products
      summary: List products.
      parameters:
        - type: integer
          description: >-
            Pagination limit on numbers of products to return, default 100, max
            100.
          name: limit
          in: query
        - type: string
          description: >-
            Pagination cursor. Leave blank or exclude in the first request. For
            subsequent requests, use the `next` value from the previous
            response.
          name: cursor
          in: query
        - type: string
          description: Optional filter on group.
          name: groupId
          in: query
        - type: string
          description: >-
            Optional filter on product category, either 'bought' or 'sold'.
            Defaults to both.
          name: filter
          in: query
        - type: string
          description: Optional filter on product customId.
          name: customId
          in: query
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ListProductsResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /products/updates:
    get:
      description: >-
        List IDs products which have updates to their footprint information.

        Fetch each product to see the relevant information.

        Use updated_at of the last item in the list to progress the pagination.

        The since parameter is inclusive, so pages may repeat the last item of
        the previous page.

        Avoid a since parameter too close to wall time, since then in flight
        updates may be missed.
      produces:
        - application/json
      tags:
        - Products
      summary: List IDs of products that have updated footprint information
      parameters:
        - type: string
          example: '`2018-03-20T09:12:28.999999999Z`'
          description: >-
            List updates since this RFC3339 timestamp (with sub-second
            resolution). Functions as pagination offset.
          name: since
          in: query
        - type: integer
          description: Pagination limit (1-256), default 100.
          name: limit
          in: query
        - type: string
          format: uuid
          description: Optional filter on group. Defaults to all accessible groups.
          name: groupId
          in: query
        - type: string
          description: >-
            Optional filter on product category, either 'bought' or 'sold'.
            Defaults to both.
          name: filter
          in: query
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Update'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /products/{product-id}:
    get:
      description: Get a product by its unique ID.
      produces:
        - application/json
      tags:
        - Products
      summary: Get specific product.
      parameters:
        - type: string
          description: Product (UUID) ID.
          name: product-id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ProductResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  BasicFootprint:
    description: >-
      Climate footprint kg C02e per kg. Calculated according to
      `calculationMethod`.
    type: object
    required:
      - calculationMethod
      - embeddedFossilResources
      - flag
      - other
      - packaging
      - processing
      - storage
      - total
      - transportation
      - updatedAt
    properties:
      calculationMethod:
        type: string
        enum:
          - location
          - market
      embeddedFossilResources:
        type: number
      flag:
        type: number
      nonFlag:
        type: number
      other:
        type: number
      packaging:
        type: number
      processing:
        type: number
      storage:
        type: number
      total:
        type: number
      transportation:
        type: number
      updatedAt:
        type: string
        format: date-time
  CreateProductRequest:
    type: object
    required:
      - batchSizeKg
      - groupId
      - market
      - name
      - productionLocation
    properties:
      batchSizeKg:
        type: number
        minimum: 0
      categories:
        type: array
        items:
          type: string
      customId:
        type: string
        maxLength: 255
      description:
        type: string
      groupId:
        type: string
      gtin:
        type: string
        maxLength: 14
      imageBase64:
        type: string
      imageUrl:
        type: string
      ingredients:
        type: string
      market:
        type: string
      name:
        type: string
        maxLength: 255
        minLength: 3
      processingLocation:
        type: string
      productionLocation:
        type: string
      yearlySalesVolumes:
        $ref: '#/definitions/SalesVolumes'
  Error:
    description: A generic error response
    type: object
    properties:
      error:
        type: string
  FlagFootprint:
    description: >-
      Climate footprint kg C02e per kg with forest, land and agriculture
      breakdown. Calculated according to `calculationMethod`.
    type: object
    required:
      - calculationMethod
      - embeddedFossilResources
      - flag
      - other
      - packaging
      - processing
      - storage
      - total
      - transportation
      - updatedAt
    properties:
      calculationMethod:
        type: string
        enum:
          - location
          - market
      embeddedFossilResources:
        type: number
      flag:
        $ref: '#/definitions/publicapi.FlagBreakdown'
      other:
        type: number
      packaging:
        type: number
      processing:
        type: number
      storage:
        type: number
      total:
        type: number
      transportation:
        type: number
      updatedAt:
        type: string
        format: date-time
  Group:
    type: object
    required:
      - id
      - name
    properties:
      id:
        description: Group ID.
        type: string
        format: uuid
      name:
        description: Name of group.
        type: string
  ListProductsResponse:
    type: object
    required:
      - page
      - products
    properties:
      page:
        $ref: '#/definitions/PageInfo'
      products:
        type: array
        items:
          $ref: '#/definitions/Product'
  PageInfo:
    type: object
    required:
      - cursor
      - next
    properties:
      cursor:
        description: Cursor points to the start of this page.
        type: string
      next:
        description: >-
          Next cursor points to the start of the next page. Empty if there is no
          next page.
        type: string
  Product:
    type: object
    required:
      - groupId
      - id
      - name
      - public
    properties:
      batchSizeKg:
        type: number
      categories:
        type: array
        items:
          type: string
      climatehubUrl:
        description: |-
          URL to the products ClimateHub report.
          Only available if the product is public.
        type: string
      createdAt:
        type: string
        format: date-time
      customId:
        type: string
      description:
        type: string
      groupId:
        description: GroupID of owner group.
        type: string
        format: uuid
      gtin:
        type: string
      id:
        type: string
      ingredients:
        type: string
      market:
        type: string
      name:
        type: string
      processingLocation:
        type: string
      productionLocation:
        type: string
      public:
        type: boolean
      updatedAt:
        type: string
        format: date-time
      yearlySalesVolumes:
        $ref: '#/definitions/SalesVolumes'
  ProductResponse:
    type: object
    required:
      - product
    properties:
      footprint:
        description: 'Deprecated: Use the /products/:id:/footprint endpoint instead.'
        type: object
      product:
        $ref: '#/definitions/Product'
  SalesVolumes:
    description: 'Sales volumes in kg/year. Object with fields like "2025": 123.0,'
    type: object
    additionalProperties:
      type: number
  Total:
    type: object
    required:
      - sum
    properties:
      ch4:
        type: number
      co2:
        type: number
      n2o:
        type: number
      sum:
        type: number
  Update:
    type: object
    required:
      - productId
      - updatedAt
    properties:
      productId:
        type: string
      updatedAt:
        type: string
        format: date-time
  UpdateProductRequest:
    description: >-
      Update an existing product by its unique ID. Only provided fields will be
      updated.
    type: object
    properties:
      batchSizeKg:
        type: number
        minimum: 0
      categories:
        type: array
        items:
          type: string
      customId:
        type: string
        maxLength: 255
      description:
        type: string
      gtin:
        type: string
        maxLength: 14
      imageBase64:
        type: string
      imageUrl:
        type: string
      ingredients:
        type: string
      name:
        type: string
        maxLength: 255
        minLength: 3
      processingLocation:
        type: string
      productionLocation:
        type: string
  publicapi.FlagBreakdown:
    type: object
    properties:
      carbonRemovals:
        type: number
      landManagementCO2:
        $ref: '#/definitions/publicapi.LandManagementCO2Breakdown'
      landManagementNonCO2:
        $ref: '#/definitions/publicapi.LandManagementNonCO2Breakdown'
      landUseChange:
        $ref: '#/definitions/publicapi.LandUseChangeBreakdown'
      total:
        $ref: '#/definitions/Total'
  publicapi.LandManagementCO2Breakdown:
    type: object
    properties:
      organicSoilsCO2:
        type: number
      total:
        $ref: '#/definitions/Total'
  publicapi.LandManagementNonCO2Breakdown:
    type: object
    properties:
      directEmissionsN2O:
        type: number
      dryingCO2:
        type: number
      farmMachineryCO2:
        type: number
      fertilizerProductionCO2:
        type: number
      fertilizerProductionN2O:
        type: number
      indirectEmissionsN2O:
        type: number
      irrigationCO2:
        type: number
      limestoneAndUreaCO2:
        type: number
      organicSoilsN2O:
        type: number
      pesticideProductionCO2:
        type: number
      riceCultivationCH4:
        type: number
      total:
        $ref: '#/definitions/Total'
  publicapi.LandUseChangeBreakdown:
    type: object
    properties:
      deforestationCO2:
        type: number
      total:
        $ref: '#/definitions/Total'
