openapi: 3.1.0
info:
  title: Verdra Carbon Footprint API
  version: "2026-05-13"
  summary: Public screening API for carbon footprint estimates
  description: |
    Verdra lets AI agents estimate a company's annual carbon footprint for SME baselining,
    supplier Scope 3 requests, RSE tenders, and CSRD-readiness screening.

    Use quick mode when only sector, headcount band, and revenue band are known.
    Use detailed mode when the caller has monthly energy, office, and travel inputs.

    This API returns screening estimates and interpretation. It is not a certified audit,
    legal opinion, or formal BEGES filing.
servers:
  - url: https://verdra.nanocorp.app
paths:
  /api/v1/footprint:
    post:
      operationId: verdraCalculateCarbonFootprint
      summary: Estimate a company carbon footprint
      description: |
        Returns either a range or a detailed screening estimate in tCO2e/year plus
        hotspots, compliance signals, next steps, and disclaimers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerdraFootprintRequest"
            examples:
              detailed:
                summary: Detailed screening estimate
                value:
                  company_name: Atelier Durand
                  country_code: FR
                  calculation_mode: detailed
                  business_contexts:
                    - supplier_scope3
                    - rse_tender
                  industry: construction_btp
                  employees: 42
                  office_size_m2: 680
                  electricity_kwh_per_month: 5400
                  gas_m3_per_month: 420
                  short_flights_per_month: 1
                  long_flights_per_month: 0
      responses:
        "200":
          description: Screening estimate returned successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerdraFootprintResponse"
              examples:
                detailed:
                  summary: Detailed activity-based screening response
                  value:
                    tool: verdra_calculate_carbon_footprint
                    version: "2026-05-13"
                    company_name: Atelier Durand
                    country_code: FR
                    calculation_mode: detailed
                    estimate_type: activity_based_screening
                    estimate:
                      annual_emissions_tco2e: 133.1
                      scope_breakdown_tco2e:
                        scope_1_2_proxy: 22
                        scope_3_people_and_travel_proxy: 61.2
                        scope_3_supply_chain_proxy: 49.9
                      line_items_tco2e:
                        electricity: 3.7
                        gas: 10.1
                        office_energy_proxy: 8.2
                        employee_commuting_proxy: 58.8
                        business_travel_proxy: 2.4
                        supply_chain_proxy: 49.9
                    interpretation:
                      summary: Verdra estimates Atelier Durand's annual footprint at 133.1 tCO2e/year from the supplied operational proxies and sector multiplier.
                      likely_primary_drivers:
                        - Employee commuting proxy
                        - Supply chain / purchased goods proxy
                        - Gas
                      business_context_guidance:
                        - Surface the scope 3 proxy clearly because large customers usually care about supplier data quality, refresh cadence, and reduction actions more than a single topline number.
                        - Use the estimate to answer tender pre-qualification questions, then attach methodology notes and next-step evidence if a buyer asks for supporting detail.
                      compliance_signals:
                        - For most standalone French SMEs below the large-enterprise thresholds, the immediate pressure is usually commercial or supply-chain driven rather than a direct BEGES filing duty.
                        - Supplier and CSRD questionnaires typically expect scope context, methodology notes, and refresh cadence, not just a topline tCO2e number.
                        - For RSE or procurement tenders, the estimate is usually strongest when paired with a reduction plan and a short explanation of assumptions.
                      recommended_next_steps:
                        - Review the biggest proxy lines first and replace proxy data with invoices or ledger exports where possible.
                        - Validate the organizational perimeter and reporting year before sharing the estimate externally.
                        - Collect the highest-impact activity data next: energy bills, fuel, travel, and top purchasing categories.
                        - If the estimate will be shown to a client or buyer, attach methodology notes and key assumptions.
                        - Order Verdra's full report if you need a shareable deliverable for procurement, CSRD readiness, or auditor discussions.
                    methodology:
                      calculator_version: verdra-screening-api-2026-05-13
                      standards_alignment:
                        - GHG Protocol
                        - ISO 14064-1 aligned workflow
                        - ADEME-inspired factors
                      source_links:
                        - https://verdra.nanocorp.app/methodologie
                        - https://verdra.nanocorp.app/calculateur
                    disclaimers:
                      - This endpoint returns a screening estimate, not a certified audit, not a legal opinion, and not a formal BEGES filing.
                      - Results depend on the data supplied by the caller and Verdra's current calculator assumptions.
                      - Scope 3 in particular is partly estimated from sector multipliers and should be refined before external assurance or contractual use.
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  fields:
                    type: array
                    items:
                      type: string
        "500":
          description: Internal calculation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    VerdraFootprintRequest:
      type: object
      properties:
        company_name:
          type: string
          description: Company name shown back in the result
        country_code:
          type: string
          description: ISO country code, default FR
        calculation_mode:
          type: string
          enum:
            - quick
            - detailed
          description: quick for coarse estimates, detailed for activity-based screening
        business_contexts:
          type: array
          description: Optional use cases that tune the interpretation layer
          items:
            type: string
            enum:
              - customer_carbon_request
              - rse_tender
              - csrd_screening
              - supplier_scope3
              - internal_baseline
        include_interpretation:
          type: boolean
          description: Defaults to true
        quick_sector:
          type: string
          description: Required in quick mode
          enum:
            - industry
            - transport_logistics
            - services
            - commerce
            - agriculture_agro
            - construction
        employee_band:
          type: string
          description: Required in quick mode
          enum:
            - 1_10
            - 11_50
            - 51_250
            - 250_plus
        revenue_band:
          type: string
          description: Required in quick mode
          enum:
            - lt_500k
            - 500k_2m
            - 2m_10m
            - 10m_50m
            - gt_50m
        industry:
          type: string
          description: Required in detailed mode
          enum:
            - technology_software
            - professional_services
            - commerce_ecommerce
            - industry_manufacturing
            - healthcare
            - construction_btp
            - food_agriculture
            - transport_logistics
            - finance_insurance
            - education_training
            - other
        employees:
          type: number
        office_size_m2:
          type: number
        electricity_kwh_per_month:
          type: number
        gas_m3_per_month:
          type: number
        short_flights_per_month:
          type: number
        long_flights_per_month:
          type: number
      required:
        - calculation_mode
    VerdraFootprintResponse:
      type: object
      properties:
        tool:
          type: string
        version:
          type: string
        company_name:
          type: string
        country_code:
          type: string
        calculation_mode:
          type: string
          enum:
            - quick
            - detailed
        estimate_type:
          type: string
          enum:
            - screening_range
            - activity_based_screening
        estimate:
          type: object
          description: Quick mode returns a range; detailed mode returns a single screening estimate
        interpretation:
          type: object
          nullable: true
        methodology:
          type: object
        disclaimers:
          type: array
          items:
            type: string