openapi: 3.0.3
info:
  title: Emitwise API
  version: v1
  description: |
    The Emitwise API allows customers to interact with the Emitwise carbon
    accounting platform programmatically. The API exposes facilities, projects,
    schema metadata, file uploads of activity data, and aggregated supplier
    emissions data so customers can integrate Scope 1, 2, and 3 emissions
    measurement and product carbon footprint (PCF) workflows into their own
    systems.

    Access requires an Emitwise customer account; new API keys are created from
    the Company settings area of the dashboard and presented to the API as
    bearer credentials. As of July 2025, Emitwise has been acquired by Green
    Project Technologies; the API and developer portal remain live at
    api.emitwise.com and docs.emitwise.com while the platform is integrated
    into Green Project's broader decarbonization product.
  contact:
    name: Emitwise (Green Project Technologies)
    url: https://docs.emitwise.com/
  license:
    name: Proprietary
servers:
  - url: https://api.emitwise.com/v1
    description: Production
tags:
  - name: Facilities
    description: Physical or virtual locations whose emissions are tracked.
  - name: Projects
    description: Sustainability initiatives that group emissions data.
  - name: Schema
    description: Activity data schema definitions.
  - name: Files
    description: Activity-data file uploads used to calculate emissions.
  - name: Suppliers
    description: Aggregated Scope 3 supplier emissions data.
security:
  - bearerAuth: []
paths:
  /facilities:
    get:
      tags: [Facilities]
      summary: List Facilities
      description: List all facilities (offices, factories, business units) tracked in the customer's Emitwise account.
      operationId: listFacilities
      responses:
        '200':
          description: A paginated list of facilities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Facility'
  /projects:
    get:
      tags: [Projects]
      summary: List Projects
      description: List all sustainability projects associated with the customer's organization.
      operationId: listProjects
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
  /schema:
    get:
      tags: [Schema]
      summary: Get Activity Data Schema
      description: Retrieve the schema definition used to validate uploaded activity data files.
      operationId: getSchema
      responses:
        '200':
          description: The active schema definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
  /files:
    post:
      tags: [Files]
      summary: Upload Activity Data File
      description: Upload a tabular activity-data file (matching the active schema) so emissions can be calculated.
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The tabular activity-data file (CSV or similar).
                facilityId:
                  type: string
                  description: Optional facility the file applies to.
                projectId:
                  type: string
                  description: Optional project the file applies to.
      responses:
        '201':
          description: File accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
    get:
      tags: [Files]
      summary: List Files
      description: List previously uploaded activity-data files.
      operationId: listFiles
      responses:
        '200':
          description: A list of uploaded files.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
  /files/{fileId}:
    get:
      tags: [Files]
      summary: Get File
      description: Retrieve details and processing status for a previously uploaded file.
      operationId: getFile
      parameters:
        - in: path
          name: fileId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: File details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
  /suppliers/list:
    post:
      tags: [Suppliers]
      summary: List Suppliers (Paginated)
      description: Retrieve aggregated supplier emissions data with pagination and filtering. Suppliers are automatically identified from spend data uploaded by the customer.
      operationId: listSuppliers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  minimum: 1
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 200
                filters:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: A paginated supplier list with aggregated emissions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Supplier'
                  page:
                    type: integer
                  pageSize:
                    type: integer
                  total:
                    type: integer
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Emitwise API key generated from Company settings, presented as a Bearer token.
  schemas:
    Facility:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: Physical or virtual classification (e.g. office, factory, business unit).
        location:
          type: string
        country:
          type: string
    Project:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
    Schema:
      type: object
      description: Active schema definition for activity-data files.
      properties:
        version:
          type: string
        fields:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              required:
                type: boolean
              description:
                type: string
    File:
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        status:
          type: string
          enum: [uploaded, processing, processed, failed]
        uploadedAt:
          type: string
          format: date-time
        facilityId:
          type: string
          nullable: true
        projectId:
          type: string
          nullable: true
    Supplier:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        totalSpend:
          type: number
          description: Total spend with this supplier across the reporting period.
        currency:
          type: string
        emissions:
          type: object
          properties:
            scope3:
              type: number
              description: Scope 3 supplier emissions in kgCO2e.
            unit:
              type: string
              example: kgCO2e