CarbonGuru History API

openapi: 3.2.0
info:
  title: CarbonGuru History API
  version: 0.1.0
  summary: Carbon footprint analysis, history and reference data for a developer's own server.
  description: 'One API over the CarbonGuru platform: carbon-footprint analysis of products, carts, text, structured items and files; the sessions, exports and history those analyses produce; reference data; offsets for the account itself; and, for an account with a connected store, catalog footprints, the live footprint read, offset ordering and webhooks. Authenticate with `Authorization: Bearer `. A test key, made in the same place, connects the same way and records every order it posts as a preview: nothing is bought. Errors are RFC 9457 problem documents. Every response carries `X-Request-ID`. Writes accept an `Idempotency-Key`. Lists page with an opaque `next_cursor`. No route accepts terms, saves a payment method or starts automatic offsetting: a signed-in person does those in the account.'
  contact:
    name: CarbonGuru
    url: https://carbonguru.io
servers:
- url: https://carbonguru.io
  description: Production
security:
- bearerAuth: []
tags:
- name: History
  description: Past analyses, footprints and account usage.
paths:
  /v1/sessions:
    get:
      tags:
      - History
      operationId: listSessions
      summary: Recent cart and order analyses
      description: Each entry is a Session resource carrying its items, the same shape GET /v1/sessions/{session_id} returns.
      security:
      - bearerAuth:
        - carbon:read
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 50
      responses:
        '200':
          description: The account's recent analyses, newest first.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
  /v1/footprints/search:
    get:
      tags:
      - History
      operationId: searchFootprints
      summary: Search the account's footprint history
      security:
      - bearerAuth:
        - carbon:read
      parameters:
      - name: search
        in: query
        schema:
          type: string
        description: Product name or CarbonGuru id.
      - name: url
        in: query
        schema:
          type: string
      - name: date_from
        in: query
        schema:
          type: string
          format: date
      - name: date_to
        in: query
        schema:
          type: string
          format: date
      - name: category
        in: query
        schema:
          type: string
      - name: merchant
        in: query
        schema:
          type: string
      - name: min_carbon
        in: query
        schema:
          type: number
      - name: max_carbon
        in: query
        schema:
          type: number
      - name: sort_by
        in: query
        schema:
          type: string
          enum:
          - date
          - carbon_desc
          - carbon_asc
          - price
          default: date
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: The account's matching footprints as Item resources, plus one global semantic match when `search` was given.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FootprintSearch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
  /v1/usage:
    get:
      tags:
      - History
      operationId: getUsage
      summary: Account identity, plan and lifetime analysis totals
      description: 'account and plan come from the platform''s whoami read; lifetime comes from its analysis-stats read. period is null: analyses this period, the allowance and the reset date need the one allowance principal of ADR-010 stage 0l, which is not built, and no number is invented in the meantime.'
      security:
      - bearerAuth:
        - carbon:read
      responses:
        '200':
          description: The account's usage summary.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Usage:
      type: object
      properties:
        account:
          type: object
          properties:
            user_id:
              type: string
            email:
              type:
              - string
              - 'null'
            display_name:
              type:
              - string
              - 'null'
            account_type:
              type: string
            member_since:
              type:
              - string
              - 'null'
        scopes:
          type:
          - array
          - 'null'
          items:
            type: string
        plan:
          type:
          - object
          - 'null'
          description: The account's CarbonGuru subscription, as the platform reports it.
        lifetime:
          type: object
          properties:
            total_items:
              type:
              - integer
              - 'null'
            total_carbon_kg:
              type:
              - number
              - 'null'
            avg_carbon_kg:
              type:
              - number
              - 'null'
            total_sessions:
              type:
              - integer
              - 'null'
        period:
          type: 'null'
          description: Analyses this period, allowance and reset date. Not served yet; no number is invented.
    Problem:
      type: object
      description: RFC 9457 problem document. Served as application/problem+json.
      required:
      - type
      - title
      - status
      - detail
      - code
      - request_id
      properties:
        type:
          type: string
          description: A stable identifier for this problem kind.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: The machine-readable name to branch on.
        request_id:
          type: string
        errors:
          type: array
          description: Field-level problems, when the refusal is about the request's fields.
          items:
            type: object
        required_scope:
          type: string
          description: Present on insufficient_scope.
        retry_after:
          type: string
          description: Present on a 429, beside the Retry-After header.
        max_size_bytes:
          type: integer
          description: Present on file_too_large.
        min_tier:
          type: string
          description: Present on feature_not_entitled.
        current_tier:
          type: string
          description: Present on feature_not_entitled.
        upgrade_url:
          type: string
          description: Present on feature_not_entitled.
        details:
          type: object
          description: Present on mapping_limit_exceeded.
    Session:
      type: object
      description: One analysis session and its items. As with Item, the fields below are the whole resource.
      properties:
        id:
          type: string
        status:
          type:
          - string
          - 'null'
          enum:
          - running
          - completed
          - failed
          - incomplete
          - null
        error:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        source_type:
          type:
          - string
          - 'null'
        analysis_type:
          type:
          - string
          - 'null'
        lca_type:
          type:
          - string
          - 'null'
        item_count:
          type:
          - integer
          - 'null'
        country_code:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
        merchant:
          type:
          - string
          - 'null'
        source_url:
          type:
          - string
          - 'null'
        input_urls:
          type:
          - array
          - 'null'
          items:
            type: string
        total_carbon_kg:
          type:
          - number
          - 'null'
        total_price:
          type:
          - number
          - 'null'
        total_social_cost_usd:
          type:
          - number
          - 'null'
        total_offset_cost_usd:
          type:
          - number
          - 'null'
        pcf_comparison:
          type:
          - object
          - 'null'
          description: The session-level comparison for the total footprint.
        is_acted_on:
          type:
          - boolean
          - 'null'
        acted_on_date:
          type:
          - string
          - 'null'
        acted_on_count:
          type:
          - integer
          - 'null'
        actionable_count:
          type:
          - integer
          - 'null'
        orders:
          type:
          - array
          - 'null'
          items:
            type: object
        order_count:
          type:
          - integer
          - 'null'
        date_created:
          type:
          - string
          - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
    FootprintSearch:
      type: object
      required:
      - footprints
      - count
      properties:
        footprints:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        count:
          type: integer
          description: Footprints on this page.
        total_available:
          type:
          - integer
          - 'null'
          description: Footprints matching the filter across every page.
        global_semantic_match:
          type:
          - object
          - 'null'
          description: One match from the global corpus, present when `search` was given. It names no session, account or identifier.
          properties:
            found:
              type: boolean
            score:
              type:
              - number
              - 'null'
            product_name:
              type:
              - string
              - 'null'
            naics_code:
              type:
              - string
              - 'null'
            co2e_per_currency_unit:
              type:
              - number
              - 'null'
            carbon_kg:
              type:
              - number
              - 'null'
    Item:
      type: object
      description: 'One analysed item and its footprint. The fields below are the whole resource: a field absent from a response is one the platform holds nothing for on that item. Nothing outside this list is served, including anything added to the platform''s own row later.'
      properties:
        carbonguru_id:
          type: string
          description: The item's public handle on every CarbonGuru surface.
        session_id:
          type: string
          description: The analysis session this item belongs to.
        item_number:
          type: integer
          description: The item's position in its session, one-based.
        status:
          type: string
        source_type:
          type: string
          description: 'How the item entered the platform: file, url, merchant_catalog, merchant_page.'
        product_name:
          type:
          - string
          - 'null'
        activity:
          type:
          - string
          - 'null'
          description: The activity line the analysis read.
        description:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        quantity:
          type:
          - integer
          - 'null'
          description: Present when the source row carries a quantity of its own.
        price:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
          description: ISO 4217.
        price_source:
          type:
          - string
          - 'null'
        price_date:
          type:
          - string
          - 'null'
        original_url:
          type:
          - string
          - 'null'
          description: The page this item was read from.
        image_url:
          type:
          - string
          - 'null'
        merchant:
          type:
          - string
          - 'null'
        carbon_kg:
          type:
          - number
          - 'null'
          description: The footprint, kg CO2e.
        pcf:
          type:
          - number
          - 'null'
          description: The process-LCA footprint, where one applies.
        co2e_per_currency_unit:
          type:
          - number
          - 'null'
          description: 'The emission factor applied: kg CO2e per unit of the item''s currency.'
        social_cost_usd:
          type:
          - number
          - 'null'
          description: Social cost of carbon, USD (EPA 2023).
        offset_cost_usd:
          type:
          - number
          - 'null'
        offset_provider:
          type:
          - string
          - 'null'
        offset_product_id:
          type:
          - string
          - 'null'
        offset_quote_source:
          type:
          - string
          - 'null'
        offset_cache_age_s:
          type:
          - integer
          - 'null'
          description: Age of this quote in seconds.
        offset_requested_qty_tons:
          type:
          - number
          - 'null'
        offset_orderable_qty_tons:
          type:
          - number
          - 'null'
        offset_provider_min_tons:
          type:
          - number
          - 'null'
        offset_display_cost_usd:
          type:
          - number
          - 'null'
        offset_orderable_cost_usd:
          type:
          - number
          - 'null'
        offset_defaults_applied:
          type:
          - boolean
          - 'null'
        offset_warnings:
          type:
          - array
          - 'null'
          items: {}
        is_offset:
          type:
          - boolean
          - 'null'
          description: The account has bought offsets for this footprint.
        is_removal:
          type:
          - boolean
          - 'null'
          description: The account has bought removals for this footprint.
        offset_type:
          type:
          - string
          - 'null'
          enum:
          - offset
          - removal
          - null
        offset_status:
          type:
          - string
          - 'null'
        offset_date:
          type:
          - string
          - 'null'
        is_acted_on:
          type:
          - boolean
          - 'null'
        acted_on_date:
          type:
          - string
          - 'null'
        lca_type:
          type:
          - string
          - 'null'
          enum:
          - eio
          - process
          - null
        naics_code:
          type:
          - string
          - 'null'
        naics_title:
          type:
          - string
          - 'null'
        naics_vintage:
          type:
          - string
          - 'null'
          description: 2017 or 2022. Null on rows written before the column existed.
        factor_naics_code_2017:
          type:
          - string
          - 'null'
          description: The USEEIO factor code the footprint was computed from.
        sector_code:
          type:
          - string
          - 'null'
          description: Open CEDA sector code, for a non-US country.
        sector_name:
          type:
          - string
          - 'null'
        emission_factor_source:
          type:
          - string
          - 'null'
          description: USEEIO, Open CEDA, and so on.
        impact_factor_name:
          type:
          - string
          - 'null'
        impact_factor_id:
          type:
          - string
          - 'null'
        reference_product:
          type:
          - string
          - 'null'
        mapping_strategy:
          type:
          - string
          - 'null'
          description: How the item was classified.
        justification:
          type:
          - string
          - 'null'
          description: Why this classification was chosen.
        country_code:
          type:
          - string
          - 'null'
          description: ISO 3-letter code the footprint was calculated for.
        country_detection_method:
          type:
          - string
          - 'null'
          description: 'How the country was determined: declared, llm, meta, tld.'
        price_adjusted:
          type:
          - number
          - 'null'
          description: The price deflated to the factor's reference year.
        price_reference_year:
          type:
          - integer
          - 'null'
        price_adjustment_factor:
          type:
          - number
          - 'null'
        price_adjustment_applied:
          type:
          - boolean
          - 'null'
        manual_price:
          type:
          - number
          - 'null'
        manual_carbon_footprint:
          type:
          - number
          - 'null'
        manual_price_date:
          type:
          - string
          - 'null'
        manual_price_source:
          type:
          - string
          - 'null'
        original_price:
          type:
          - number
          - 'null'
          description: The price a manual override replaced.
        original_carbon_footprint:
          type:
          - number
          - 'null'
          description: The footprint a manual override replaced.
        correction_date:
          type:
          - string
          - 'null'
        correction_reason:
          type:
          - string
          - 'null'
        pcf_comparison:
          type:
          - object
          - 'null'
          description: The full comparison against a reference product.
        pcf_comparison_product_name:
          type:
          - string
          - 'null'
        pcf_comparison_sector:
          type:
          - string
          - 'null'
        pcf_comparison_country:
          type:
          - string
          - 'null'
        pcf_comparison_pcf_value:
          type:
          - number
          - 'null'
          description: The reference PCF, kg CO2e.
        pcf_comparison_percent_diff:
          type:
          - number
          - 'null'
        pcf_comparison_status:
          type:
          - string
          - 'null'
          enum:
          - higher
          - lower
          - similar
          - no_match
          - null
        pcf_comparison_timestamp:
          type:
          - string
          - 'null'
        product_sku:
          type:
          - string
          - 'null'
        product_upc:
          type:
          - string
          - 'null'
        product_mpn:
          type:
          - string
          - 'null'
        product_model_number:
          type:
          - string
          - 'null'
        product_brand_part_number:
          type:
          - string
          - 'null'
        product_asin:
          type:
          - string
          - 'null'
        product_gtin:
          type:
          - string
          - 'null'
        product_item_number:
          type:
          - string
          - 'null'
        manufacturer_sku:
          type:
          - string
          - 'null'
        part_number:
          type:
          - string
          - 'null'
        product_identifiers:
          type:
          - object
          - 'null'
        order_number:
          type:
          - string
          - 'null'
        order_index:
          type:
          - integer
          - 'null'
        wc_product_url:
          type:
          - string
          - 'null'
          description: The footprint page for this item.
        analyzed_at:
          type:
          - string
          - 'null'
    SessionList:
      type: object
      required:
      - sessions
      - count
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        count:
          type: integer
  headers:
    XRequestID:
      description: The request id, echoed from the caller when it is a sane token, else minted. On every response and in every log line.
      schema:
        type: string
  responses:
    Forbidden:
      description: A missing scope, an exhausted analysis allowance, or an object that is not the caller's.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: No valid credential. Every authentication failure returns this one document.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UnprocessableContent:
      description: The request's fields are wrong. errors[] names them.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key from /my-account/api/ (`sk_merchant_…`), or a CarbonGuru OAuth access token. A test key (`sk_merchant_test_…`) connects like a live key; every order it posts is recorded as a preview and nothing is bought. Auth runs before body validation, and every failure returns the same 401.