myco2suite-io API

openapi: 3.1.0
info:
  title: myco2suite-io API
  version: '2026-10-30'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-30: 14 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; myco2suite-io has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 13
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-30'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://api.myco2suite.io
paths:
  /.well-known/agent-card.json:
    get:
      operationId: get_well_known_agent_card_json
      tags:
      - API
      summary: Agent card
      x-source: https://api.myco2suite.io
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/acp:
    get:
      operationId: get_v1_acp
      tags:
      - Acp
      summary: ACP root
      x-source: https://api.myco2suite.io
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/activity:
    post:
      operationId: post_v1_activity
      tags:
      - Activity
      summary: POST /v1/activity
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ActivityRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.myco2suite.io/v1/activity  -H \"Content-Type: application/json\"  -H \"x-api-key: YOUR_API_KEY\"  -d '{\n \"\
          activity_type\": \"electricity\",\n \"quantity\": 500,\n \"country\": \"DE\"\n }'"
  /v1/activity-types:
    get:
      operationId: get_v1_activity_types
      tags:
      - Activity Types
      summary: Search and browse the activity catalogue — what you can calculate, in which countries and units.
      x-source: https://api.myco2suite.io
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Free-text search
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: Filter by category (fuels, electricity, materials…)
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Only types available for this country
      - name: year
        in: query
        required: false
        schema:
          type: number
        description: Only types with data for this year
      - name: limit
        in: query
        required: false
        schema:
          type: number
        description: Max results
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ActivityTypesResponse'
      x-evidence:
        kind: documentation
  /v1/activity/batch:
    post:
      operationId: post_v1_activity_batch
      tags:
      - Activity
      summary: Up to 100 activity calculations in one request. Each item is billed as one API call and returns its own result or error — one bad
        item never fails the batch.
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ActivityBatchRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ActivityBatchResponse'
      x-evidence:
        kind: documentation
  /v1/budget:
    post:
      operationId: post_v1_budget
      tags:
      - Budget
      summary: Running total of the emissions calculated with your API key over a period, compared against a science-based ~2 tCO2e/year budget.
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1BudgetRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1BudgetResponse'
      x-evidence:
        kind: documentation
  /v1/cbam:
    post:
      operationId: post_v1_cbam
      tags:
      - Cbam
      summary: EU CBAM import liability from a CN code, country of origin and weight — covering iron & steel, aluminium, cement, fertilisers and
        hydrogen.
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CbamRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1CbamResponse'
      x-evidence:
        kind: documentation
  /v1/cbam/batch:
    post:
      operationId: post_v1_cbam_batch
      tags:
      - Cbam
      summary: CBAM has its own batch at POST /v1/cbam/batch — same pattern with a shipments array (max 100).
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CbamBatchRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1CbamBatchResponse'
      x-evidence:
        kind: documentation
  /v1/cbam/carbon-prices:
    get:
      operationId: get_v1_cbam_carbon_prices
      tags:
      - Cbam
      summary: Reference carbon prices — live EU ETS plus national carbon-price schemes — for Art. 9 deductions and scenario modelling.
      x-source: https://api.myco2suite.io
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Country filter, e.g., EU
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Price type, e.g., ets
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CbamCarbonPricesResponse'
      x-evidence:
        kind: documentation
  /v1/cbam/cn-codes:
    get:
      operationId: get_v1_cbam_cn_codes
      tags:
      - Cbam
      summary: Search the EU CN 2026 catalogue (9,800+ codes) and check which goods are in CBAM scope.
      x-source: https://api.myco2suite.io
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search by code prefix or description
      - name: sector
        in: query
        required: false
        schema:
          type: string
        description: Filter by CBAM sector
      - name: cbam_only
        in: query
        required: false
        schema:
          type: boolean
        description: Only return in-scope goods
      - name: limit
        in: query
        required: false
        schema:
          type: number
        description: Max results
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CbamCnCodesResponse'
      x-evidence:
        kind: documentation
  /v1/factor:
    get:
      operationId: get_v1_factor
      tags:
      - Factor
      summary: Look up the underlying emission factor itself — value, unit, methodology, source, licence, gas basis and GWP version — without
        running a calculation.
      x-source: https://api.myco2suite.io
      parameters:
      - name: id
        in: query
        required: false
        schema:
          type: string
        description: Exact re-fetch of the factor a previous response used
      - name: activity_type
        in: query
        required: false
        schema:
          type: string
        description: Activity slug (or use an industry code below)
      - name: mcc
        in: query
        required: false
        schema:
          type: string
        description: Any one industry classification code
      - name: bea_code
        in: query
        required: false
        schema:
          type: string
      - name: naics
        in: query
        required: false
        schema:
          type: string
      - name: isic
        in: query
        required: false
        schema:
          type: string
      - name: sic
        in: query
        required: false
        schema:
          type: string
      - name: nace
        in: query
        required: false
        schema:
          type: string
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: year
        in: query
        required: false
        schema:
          type: number
      - name: gwp_version
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1FactorResponse'
      x-evidence:
        kind: documentation
  /v1/flight:
    post:
      operationId: post_v1_flight
      tags:
      - Flight
      summary: POST /v1/flight
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FlightRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1FlightResponse'
      x-evidence:
        kind: documentation
  /v1/freight:
    post:
      operationId: post_v1_freight
      tags:
      - Freight
      summary: Freight emissions by mode — road, rail, sea or air — from origin/destination (or coordinates) and cargo weight.
      x-source: https://api.myco2suite.io
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FreightRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1FreightResponse'
      x-evidence:
        kind: documentation
  /v1/transaction:
    post:
      operationId: post_v1_transaction
      tags:
      - Transaction
      summary: Spend-based emissions (Scope 3.1). Provide a spend amount, currency, country, and any one industry classification code — mcc, bea_code,
        naics, isic, sic or nace.
      x-source: https://api.myco2suite.io
      parameters:
      - name: spend_amount
        in: query
        required: true
        schema:
          type: number
        description: Spend in the given currency
      - name: currency
        in: query
        required: true
        schema:
          type: string
        description: ISO 4217 code (USD, EUR, GBP…)
      - name: country
        in: query
        required: true
        schema:
          type: string
        description: ISO 3166-1 alpha-2 country code
      - name: mcc
        in: query
        required: false
        schema:
          type: string
        description: Merchant Category Code (4 digits). Provide any one of mcc / bea_code / naics / isic / sic / nace.
      - name: bea_code
        in: query
        required: false
        schema:
          type: string
        description: US BEA input-output sector (5–7 alphanumeric)
      - name: naics
        in: query
        required: false
        schema:
          type: string
        description: NAICS (6 digits)
      - name: isic
        in: query
        required: false
        schema:
          type: string
        description: ISIC (4 digits)
      - name: sic
        in: query
        required: false
        schema:
          type: string
        description: SIC (2–5 digits)
      - name: nace
        in: query
        required: false
        schema:
          type: string
        description: NACE (e.g. 47.11)
      - name: commodity
        in: query
        required: false
        schema:
          type: string
        description: Plain-language commodity description (Canada only)
      - name: spend_year
        in: query
        required: false
        schema:
          type: number
        description: Year the money was spent — enables inflation adjustment
      - name: adjust_for_inflation
        in: query
        required: false
        schema:
          type: boolean
        description: Deflate spend to the factor's price year (World Bank deflators)
      - name: display_currency
        in: query
        required: false
        schema:
          type: string
        description: Return converted amounts in this currency
      - name: gwp_version
        in: query
        required: false
        schema:
          type: string
        description: AR4, AR5 or AR6 — report on the GWP standard you need
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TransactionRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1TransactionResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1ActivityRequest:
      type: object
      properties:
        activity_type:
          type: string
        quantity:
          type: integer
        country:
          type: string
    GetV1ActivityTypesResponse:
      type: object
      properties:
        activity_types:
          type: array
    PostV1ActivityBatchRequest:
      type: object
      properties:
        calculations:
          type: array
          description: Array of activity calculation objects
      required:
      - calculations
    PostV1ActivityBatchResponse:
      type: object
      properties:
        results:
          type: array
    PostV1BudgetRequest:
      type: object
      properties:
        period:
          type: string
          description: day | week | month | year
      required:
      - period
    PostV1BudgetResponse:
      type: object
      properties:
        budget:
          type: object
    PostV1CbamRequest:
      type: object
      properties:
        cn_code:
          type: string
        origin_country:
          type: string
        weight_tonnes:
          type: number
        year:
          type: number
        carbon_price_paid_eur_per_tonne:
          type: number
        project:
          type: boolean
        actual_emissions_tco2e_per_t:
          type: number
        carbon_price_rebate_eur_per_tonne:
          type: number
      required:
      - cn_code
      - origin_country
      - weight_tonnes
      - year
    PostV1CbamResponse:
      type: object
      properties:
        liability:
          type: object
    PostV1CbamBatchRequest:
      type: object
      properties:
        shipments:
          type: array
          description: Array of CBAM shipment objects
      required:
      - shipments
    PostV1CbamBatchResponse:
      type: object
      properties:
        results:
          type: array
    GetV1CbamCarbonPricesResponse:
      type: object
      properties:
        prices:
          type: array
    GetV1CbamCnCodesResponse:
      type: object
      properties:
        cn_codes:
          type: array
    GetV1FactorResponse:
      type: object
      properties:
        id:
          type: string
        value:
          type: number
        unit:
          type: string
        methodology:
          type: string
        source:
          type: string
        licence:
          type: string
        gas_basis:
          type: string
        gwp_version:
          type: string
        meta.dataset_release:
          type: string
    PostV1FlightRequest:
      type: object
      properties:
        origin:
          type: string
        destination:
          type: string
        cabin_class:
          type: string
        passengers:
          type: number
        trip_type:
          type: string
        include_radiative_forcing:
          type: boolean
      required:
      - origin
      - destination
    PostV1FlightResponse:
      type: object
      properties:
        co2e_kg:
          type: number
        factor.id:
          type: string
        factor.value:
          type: number
        factor.unit:
          type: string
        factor.methodology:
          type: string
        factor.source:
          type: string
        factor.licence:
          type: string
        factor.gas_basis:
          type: string
        factor.gwp_version:
          type: string
        meta.dataset_release:
          type: string
    PostV1FreightRequest:
      type: object
      properties:
        mode:
          type: string
        origin:
          type: string
        destination:
          type: string
        weight_kg:
          type: number
        vehicle_type:
          type: string
        legs:
          type: array
      required:
      - mode
      - origin
      - destination
      - weight_kg
    PostV1FreightResponse:
      type: object
      properties:
        co2e_kg:
          type: number
        factor.id:
          type: string
        factor.value:
          type: number
        factor.unit:
          type: string
        factor.methodology:
          type: string
        factor.source:
          type: string
        factor.licence:
          type: string
        factor.gas_basis:
          type: string
        factor.gwp_version:
          type: string
        meta.dataset_release:
          type: string
    PostV1TransactionRequest:
      type: object
      properties:
        spend_amount:
          type: number
        currency:
          type: string
        country:
          type: string
        mcc:
          type: string
        bea_code:
          type: string
        naics:
          type: string
        isic:
          type: string
        sic:
          type: string
        nace:
          type: string
        commodity:
          type: string
        spend_year:
          type: number
        adjust_for_inflation:
          type: boolean
        display_currency:
          type: string
        gwp_version:
          type: string
      required:
      - spend_amount
      - currency
      - country
    PostV1TransactionResponse:
      type: object
      properties:
        co2e_kg:
          type: number
        factor.id:
          type: string
        factor.value:
          type: number
        factor.unit:
          type: string
        factor.methodology:
          type: string
        factor.source:
          type: string
        factor.licence:
          type: string
        factor.gas_basis:
          type: string
        factor.gwp_version:
          type: string
        meta.dataset_release:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
security:
- apiKey: []
tags:
- name: API
- name: Acp
- name: Activity
- name: Activity Types
- name: Budget
- name: Cbam
- name: Factor
- name: Flight
- name: Freight
- name: Transaction