Isometric Issuances API

openapi: 3.2.0
info:
  description: '# Standards


    ## Versioning


    This API will be safely versioned using root path versioning, in the format `/v{major}`.'
  title: Isometric Registry Issuances API
  version: v0
servers:
- description: Sandbox Isometric Registry API
  url: https://api.sandbox.isometric.com/registry/v0
- description: Production Isometric Registry API
  url: https://api.isometric.com/registry/v0
tags:
- name: Issuances
paths:
  /issuances:
    get:
      description: 'A paginated list of all issuances in Isometric''s registry.


        Returned list of issuances will be sorted by most recently issued first.'
      operationId: issuances_issuances_get
      parameters:
      - in: query
        name: last
        required: false
        schema:
          default: 10
          description: An integer number of items to retrieve before the item represented by the cursor passed in the before parameter. Defaults to 10 with a maximum value of 50.
          exclusiveMinimum: 0
          maximum: 50
          title: Last
          type: integer
      - in: query
        name: before
        required: false
        schema:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: An opaque cursor representing the first item in the previously requested page to select items ordered before it. Submit the previously requested page’s start_cursor here when paginated backwards.
          title: Before
      - in: query
        name: first
        required: false
        schema:
          default: 10
          description: An integer number of items to retrieve after the item represented by the cursor passed in the after parameter. Defaults to 10 with a maximum value of 50.
          exclusiveMinimum: 0
          maximum: 50
          title: First
          type: integer
      - in: query
        name: after
        required: false
        schema:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: An opaque cursor representing the last item in the previously requested page to select items ordered after it. Submit the previously requested page’s end_cursor here when paginated forwards.
          title: After
      - description: A secret token identifying the client connecting to the API
        in: header
        name: x-client-secret
        required: true
        schema:
          description: A secret token identifying the client connecting to the API
          examples:
          - Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
          title: Client secret
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListResource_Issuance_'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Issuances
      tags:
      - Issuances
  /issuances/{id}:
    get:
      description: Information about a specific issuance.
      operationId: issuance_issuances__id__get
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/IsometricIDPathParam_Issuance_'
      - description: A secret token identifying the client connecting to the API
        in: header
        name: x-client-secret
        required: true
        schema:
          description: A secret token identifying the client connecting to the API
          examples:
          - Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
          title: Client secret
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issuance'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Issuance
      tags:
      - Issuances
  /issuances/{id}/credit_batches:
    get:
      description: 'List of credit batches for a given issuance.


        Credit batches are divided between those allocated to the buffer pool and those allocated to the supplier. Note these are the original batches in the issuance, so some credit batches might be in status SPLIT if they had to be split for a delivery/transfer/retirement.'
      operationId: issuance_credit_batches_issuances__id__credit_batches_get
      parameters:
      - in: path
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/IsometricIDPathParam_Issuance_'
      - description: A secret token identifying the client connecting to the API
        in: header
        name: x-client-secret
        required: true
        schema:
          description: A secret token identifying the client connecting to the API
          examples:
          - Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
          title: Client secret
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuanceCreditBatches'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Issuance Credit Batches
      tags:
      - Issuances
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    IssuanceCreditBatches:
      properties:
        buffer_pool_credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
        buffer_pool_credit_batches:
          items:
            $ref: '#/components/schemas/CreditBatch'
          title: Buffer Pool Credit Batches
          type: array
        credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
        issuance_id:
          example: iss_1EWT8R5FY1S0GFCY
          examples:
          - iss_1EWT8R5FY1S0GFCY
          - iss_1CSVDDHH3SBXRP6K
          maxLength: 37
          minLength: 20
          title: Issuance Id
          type: string
        supplier_credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
        supplier_credit_batches:
          items:
            $ref: '#/components/schemas/CreditBatch'
          title: Supplier Credit Batches
          type: array
      required:
      - issuance_id
      - supplier_credit_batches
      - supplier_credit_batch_size_total
      - buffer_pool_credit_batches
      - buffer_pool_credit_batch_size_total
      - credit_batch_size_total
      title: IssuanceCreditBatches
      type: object
    CarbonRemovalData:
      properties:
        counterfactuals_kg:
          title: Counterfactuals Kg
          type: integer
        emissions_kg:
          title: Emissions Kg
          type: integer
        gross_carbon_removed_kg:
          title: Gross Carbon Removed Kg
          type: integer
        losses_kg:
          title: Losses Kg
          type: integer
        net_carbon_removed_kg:
          title: Net Carbon Removed Kg
          type: integer
      required:
      - gross_carbon_removed_kg
      - net_carbon_removed_kg
      - emissions_kg
      - counterfactuals_kg
      - losses_kg
      title: CarbonRemovalData
      type: object
    Supplier:
      properties:
        id:
          example: spl_1CC712KFS1S0YKPS
          examples:
          - spl_1CC712KFS1S0YKPS
          - spl_1FJBMMGR3SBXKDME
          maxLength: 37
          minLength: 20
          title: Id
          type: string
        location:
          anyOf:
          - $ref: '#/components/schemas/Location'
          - type: 'null'
        long_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Long Description
        organisation:
          $ref: '#/components/schemas/Organisation'
        short_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Short Description
      required:
      - id
      - short_description
      - long_description
      - organisation
      - location
      title: Supplier
      type: object
    IsometricIDPathParam_Issuance_:
      $ref: '#/components/schemas/IsometricIDRequestParam_Issuance_'
    Issuance:
      properties:
        buffer_pool_credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
        credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
        id:
          example: iss_1EWT8R5FY1S0GFCY
          examples:
          - iss_1EWT8R5FY1S0GFCY
          - iss_1CSVDDHH3SBXRP6K
          maxLength: 37
          minLength: 20
          title: Id
          type: string
        issued_at:
          format: date-time
          title: Issued At
          type: string
        project_id:
          example: prj_1CTWZQGKE1S0VAXA
          examples:
          - prj_1CTWZQGKE1S0VAXA
          - prj_1E0QTWB22SBX34D1
          maxLength: 37
          minLength: 20
          title: Project Id
          type: string
        reporting_period_end_at:
          description: End date of the reporting period (inclusive)
          format: date
          title: Reporting Period End At
          type: string
        reporting_period_start_at:
          description: Start date of the reporting period (inclusive)
          format: date
          title: Reporting Period Start At
          type: string
        supplier:
          $ref: '#/components/schemas/Supplier'
        supplier_credit_batch_size_total:
          $ref: '#/components/schemas/CreditQuantity'
      required:
      - id
      - issued_at
      - supplier
      - project_id
      - reporting_period_start_at
      - reporting_period_end_at
      - supplier_credit_batch_size_total
      - buffer_pool_credit_batch_size_total
      - credit_batch_size_total
      title: Issuance
      type: object
    Location:
      properties:
        country_code:
          title: Country Code
          type: string
        country_name:
          title: Country Name
          type: string
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        latitude:
          maximum: 90
          minimum: -90
          title: Latitude
          type: number
        longitude:
          maximum: 180
          minimum: -180
          title: Longitude
          type: number
      required:
      - country_code
      - country_name
      - latitude
      - longitude
      title: Location
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    CreditQuantity:
      properties:
        credit_kgs:
          description: A representation of the credit quantity as an integer kilogram amount. Where 1 unit represents 0.001 credits and 1 kilogram of CO₂e. This field can handle bigint values.
          examples:
          - 125632
          title: Credit Kgs
          type: integer
        credits:
          description: A representation of the credit quantity as a fractional amount, to 3 decimal places. Where 1 unit represents 1 credit and 1 ton of CO₂e.
          examples:
          - 125.632
          title: Credits
          type: number
      required:
      - credits
      - credit_kgs
      title: CreditQuantity
      type: object
    PageInfo:
      properties:
        end_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: End Cursor
        has_next_page:
          title: Has Next Page
          type: boolean
        has_previous_page:
          title: Has Previous Page
          type: boolean
        start_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Cursor
      required:
      - has_previous_page
      - start_cursor
      - has_next_page
      - end_cursor
      title: PageInfo
      type: object
    IsometricIDRequestParam_Issuance_:
      example: iss_1EWT8R5FY1S0GFCY
      examples:
      - iss_1EWT8R5FY1S0GFCY
      - iss_1CSVDDHH3SBXRP6K
      maxLength: 37
      minLength: 20
      type: string
    CreditBatch:
      properties:
        beneficiary:
          anyOf:
          - $ref: '#/components/schemas/Organisation'
          - type: 'null'
        carbon_removal_data:
          anyOf:
          - $ref: '#/components/schemas/CarbonRemovalData'
          - type: 'null'
          description: Carbon removal data for this credit batch
        ccp_approved:
          description: Whether this credit batch has been issued as part of a ICVCM Core Carbon Principles (CCP) approved project
          title: CCP Approved
          type: boolean
        country_of_issue:
          examples:
          - GBR
          maxLength: 3
          minLength: 3
          title: Country Of Issue
          type: string
        delivered_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Delivered At
        delivery_id:
          anyOf:
          - example: dlv_1C454ZXA61S03Z9T
            examples:
            - dlv_1C454ZXA61S03Z9T
            - dlv_1FAGG2H2PSBXHGYY
            maxLength: 37
            minLength: 20
            type: string
          - type: 'null'
          title: Delivery Id
        id:
          example: ctb_1DRBTYA8Q1S07CBY
          examples:
          - ctb_1DRBTYA8Q1S07CBY
          - ctb_1CA2D3S73SBXYN70
          maxLength: 37
          minLength: 20
          title: Id
          type: string
        issuance_id:
          example: iss_1EWT8R5FY1S0GFCY
          examples:
          - iss_1EWT8R5FY1S0GFCY
          - iss_1CSVDDHH3SBXRP6K
          maxLength: 37
          minLength: 20
          title: Issuance Id
          type: string
        issued_at:
          format: date-time
          title: Issued At
          type: string
        left_child_id:
          anyOf:
          - example: ctb_1DRBTYA8Q1S07CBY
            examples:
            - ctb_1DRBTYA8Q1S07CBY
            - ctb_1CA2D3S73SBXYN70
            maxLength: 37
            minLength: 20
            type: string
          - type: 'null'
          description: If this credit batch has status `SPLIT`, it will have two child batches representing the two halves of this split.
          title: Left Child Id
        owner:
          $ref: '#/components/schemas/Organisation'
        parent_id:
          anyOf:
          - example: ctb_1DRBTYA8Q1S07CBY
            examples:
            - ctb_1DRBTYA8Q1S07CBY
            - ctb_1CA2D3S73SBXYN70
            maxLength: 37
            minLength: 20
            type: string
          - type: 'null'
          description: If this credit batch was created from splitting a larger batch in two, this will be set to the id of the parent credit batch.
          title: Parent Id
        project_id:
          example: prj_1CTWZQGKE1S0VAXA
          examples:
          - prj_1CTWZQGKE1S0VAXA
          - prj_1E0QTWB22SBX34D1
          maxLength: 37
          minLength: 20
          title: Project Id
          type: string
        removal_id:
          example: rmv_1EEM6NJXX1S0EXKD
          examples:
          - rmv_1EEM6NJXX1S0EXKD
          - rmv_1E3V4J2EWSBX5E82
          maxLength: 37
          minLength: 20
          title: Removal Id
          type: string
        retired_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Retired At
        retirement_id:
          anyOf:
          - example: ret_1FYBH4QDT1S0SVKF
            examples:
            - ret_1FYBH4QDT1S0SVKF
            - ret_1CGV2XADRSBX1CHB
            maxLength: 37
            minLength: 20
            type: string
          - type: 'null'
          title: Retirement Id
        right_child_id:
          anyOf:
          - example: ctb_1DRBTYA8Q1S07CBY
            examples:
            - ctb_1DRBTYA8Q1S07CBY
            - ctb_1CA2D3S73SBXYN70
            maxLength: 37
            minLength: 20
            type: string
          - type: 'null'
          description: If this credit batch has status `SPLIT`, it will have two child batches representing the two halves of this split.
          title: Right Child Id
        sequestered_on:
          format: date
          title: Sequestered On
          type: string
        serial_number:
          examples:
          - ISO-1-BSTORE-GBR-F5X7-2024-78177-81177
          title: Serial Number
          type: string
        size:
          $ref: '#/components/schemas/CreditQuantity'
        status:
          $ref: '#/components/schemas/CreditBatchStatus'
        supplier_id:
          example: spl_1CC712KFS1S0YKPS
          examples:
          - spl_1CC712KFS1S0YKPS
          - spl_1FJBMMGR3SBXKDME
          maxLength: 37
          minLength: 20
          title: Supplier Id
          type: string
      required:
      - id
      - serial_number
      - status
      - size
      - issued_at
      - retired_at
      - delivered_at
      - sequestered_on
      - country_of_issue
      - supplier_id
      - parent_id
      - left_child_id
      - right_child_id
      - issuance_id
      - delivery_id
      - beneficiary
      - retirement_id
      - removal_id
      - owner
      - project_id
      - carbon_removal_data
      - ccp_approved
      title: CreditBatch
      type: object
    CreditBatchStatus:
      enum:
      - active
      - split
      - retired
      title: CreditBatchStatus
      type: string
    Organisation:
      properties:
        domain:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - isometric.com
          title: Domain
        id:
          example: org_1GB56M1ST1S0GVNA
          examples:
          - org_1GB56M1ST1S0GVNA
          - org_1CP8EQDNQSBXTMR2
          maxLength: 37
          minLength: 20
          title: Id
          type: string
        name:
          examples:
          - Isometric
          title: Name
          type: string
      required:
      - id
      - name
      - domain
      title: Organisation
      type: object
    PaginatedListResource_Issuance_:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/Issuance'
          title: Nodes
          type: array
        page_info:
          $ref: '#/components/schemas/PageInfo'
        total_count:
          title: Total Count
          type: integer
      required:
      - nodes
      - total_count
      - page_info
      title: PaginatedListResource[Issuance]
      type: object
  securitySchemes:
    HTTPBearer:
      bearerFormat: JWT
      description: 'A JWT Bearer token header for authentication and authorization, in the format `Authorization: Bearer <token>`'
      scheme: bearer
      type: http