Altruistiq Facility API

openapi: 3.0.0
info:
  title: Altruistiq Datasource Facility API
  x-logo:
    url: ./aq.svg
    altText: Altruistiq Logo
  version: 1.0.0
  description: '# Definitions


    An **Activity** is a business process that has taken place, which is relevant for emissions measurement. Examples of an **Activity** in Altruistiq’s data model are **ElectricityUse** or **WasteGenerated**.

    A **Calculation Method** is an GHG Protocol compliant method to calculate emissions from Activity data. Calculation Methods have a unique set of data requirements, but are not unique to an **Activity**.

    A **Datasource** is a single data format that your data is shared with Altruistiq in. Alongside this function, a **Datasource** plays the role of linking a data format to key contextual information (e.g. relevant **Facilities**, relevant **Activities**, owner, chosen **Calculation Methods**, status).

    **Datasets** are then individual files ingested via that Datasource. Each **Dataset** has a live status for full data lineage and transparency that you can track in the application.


    # Datasource API Outline


    Primarily, Altruistiq’s Datasource API enables the creation and management of Datasources and the upload of new Datasets. Alongside this there are a number of supporting functions.


    The Datasource API is governed by the oauth2 protocol.


    The Datasource API by default does not expect sudden bursts of data upload (e.g. 25x5GB of data transferred at once), but instead delta datasets. When uploading to the upload endpoint the files uploaded must be chunked into chunks < 100mb and if there are more than 1 part then chunks must be > 5mb (the last part can be below this). If this is not the case for your business, do raise this at your Kick Off call and we will accommodate this.


    # PACT API Outline


    Primarily, Altruistiq’s PACT API allows customers to export Product Carbon Footprint (PCF) data in a PACT conformant way. PACT is the Partnership for Carbon Transparency, a WRI and WBCSD funded NGO that is setting the calculation and technological standard for the exchange for Product Carbon Footprints between businesses. Today, Altruistiq is 1 of ~10 PACT conformant solutions globally.


    The PACT API is is governed by the oauth2 protocol (see Security).


    For full documentation of our PACT API, please go to https://wbcsd.github.io/data-exchange-protocol/v2/#api-examples. This provides the full documentation for product data exports, and the associated data model.'
servers:
- url: https://app.altruistiq.com/
  description: Altruistiq Server
tags:
- name: Facility
  description: '

    Altruistiq''s Facility API enables you to:


    - Create new facilities in bulk

    - Update existing facility persistent properties

    - Update facility version

    - Create new facility version

    - Delete facility versions

    - Delete facility

    - Get a list of facilities

    - Get a single facility



    The facility API provides comprehensive management of facility data including location, capacity, and organizational structure.

    '
paths:
  /api/public/v1/facilities/:
    get:
      operationId: FacilitiesPublicController.getFacilities
      parameters:
      - in: query
        name: search
        schema:
          type: string
          description: A search string to filter records by
          example: example search string
      - in: query
        name: pageSize
        schema:
          maximum: 1000
          type: number
          description: The number of records to return in the response
          example: 10
      - in: query
        name: pageNo
        schema:
          minimum: 1
          type: number
          description: The paginated page number of records to return
          example: 1
      - in: query
        name: buId
        schema:
          format: uuid
          type: string
          description: The UUID of the business unit
          example: dff8f526-4c6a-4ea5-b740-4762aac04699
      - in: query
        name: showClosed
        schema:
          type: boolean
          description: Whether to include closed facilities in the results
          example: false
      - in: query
        name: sortBy
        schema:
          enum:
          - facilityName
          - internalId
          - organization
          - country
          type: string
          description: The field name to sort the records on
          example: facilityName
      - in: query
        name: sortOrder
        schema:
          enum:
          - ASC
          - DESC
          type: string
          description: Ordering of the results, Ascending or Descending
          example: ASC
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilitiesPublicDtoRes'
          description: ''
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad request
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Get A List Of Facilities
      tags:
      - Facility
      description: Retrieve a paginated list of facilities with optional filtering and sorting.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/{facilityId}:
    get:
      operationId: FacilitiesPublicController.getFacility
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilityPublicDtoRes'
          description: ''
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Get A Single Facility
      tags:
      - Facility
      description: Retrieve detailed information about a specific facility.
      security:
      - bearerAuth: []
    delete:
      operationId: FacilitiesPublicController.deleteFacility
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      responses:
        '204':
          content:
            application/json: {}
          description: Successful response
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Delete A Facility
      tags:
      - Facility
      description: Delete an entire facility and all its versions.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/{facilityId}/versions/{versionId}:
    get:
      operationId: FacilitiesPublicController.getFacilityVersion
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[^\/#\?]+?'
          type: string
      - in: path
        name: versionId
        required: true
        schema:
          pattern: '[^\/#\?]+?'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilityPublicDtoRes'
          description: ''
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Get A Specific Facility Version
      tags:
      - Facility
      description: Retrieve detailed information about a specific version of a facility.
      security:
      - bearerAuth: []
    delete:
      operationId: FacilitiesPublicController.deleteFacilityVersion
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      - in: path
        name: versionId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      responses:
        '204':
          content:
            application/json: {}
          description: Successful response
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Delete A Facility Version
      tags:
      - Facility
      description: Delete a specific version of a facility.
      security:
      - bearerAuth: []
    patch:
      operationId: FacilitiesPublicController.updateFacilityVersion
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      - in: path
        name: versionId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatableFacilityVersionDTO'
        description: UpdatableFacilityVersionDTO
        required: true
      responses:
        '204':
          content:
            application/json: {}
          description: Successful response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad request
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Update A Facility Version
      tags:
      - Facility
      description: Update properties of a specific facility version.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/bulk:
    post:
      operationId: FacilitiesPublicController.bulkInsertFacilities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacilityBulkPublicDto'
        description: FacilityBulkPublicDto
        required: true
      responses:
        '201':
          content:
            application/json: {}
          description: Successful response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad request
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Create Multiple Facilities In Bulk
      tags:
      - Facility
      description: Create multiple facilities in a single request.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/{facilityId}/persistent:
    patch:
      operationId: FacilitiesPublicController.updateFacilityPersistent
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacilityPublicPersistentUpdateDTO'
        description: FacilityPublicPersistentUpdateDTO
        required: true
      responses:
        '204':
          content:
            application/json: {}
          description: Successful response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad request
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Update Facility Persistent Properties
      tags:
      - Facility
      description: Update persistent properties of a facility such as tags, internal ID, and facility type.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/{facilityId}/versions:
    post:
      operationId: FacilitiesPublicController.createFacilityVersion
      parameters:
      - in: path
        name: facilityId
        required: true
        schema:
          pattern: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFacilityVersionDTO'
        description: CreateFacilityVersionDTO
        required: true
      responses:
        '204':
          content:
            application/json: {}
          description: Successful response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad request
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Create A New Facility Version
      tags:
      - Facility
      description: Create a new version of an existing facility.
      security:
      - bearerAuth: []
  /api/public/v1/facilities/types:
    get:
      operationId: FacilitiesPublicController.getFacilityTypes
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilityTypesPublicDtoRes'
          description: ''
        '401':
          description: Not authorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Something went wrong
      summary: Get Facility Types
      tags:
      - Facility
      description: Retrieve a list of facility types available for the organization, including both generic and organization-specific types.
      security:
      - bearerAuth: []
components:
  schemas:
    FacilityGet:
      properties:
        areas:
          items:
            type: object
            $ref: '#/components/schemas/AreaGet'
          type: array
          description: Information about the areas of the facility
        versions:
          items:
            type: object
            $ref: '#/components/schemas/VersionGet'
          type: array
          description: Facility versions
        facilityId:
          format: uuid
          type: string
          description: The UUID of the facility record
          example: aee349fd-28e4-450d-9e20-af64d9c0d813
        internalId:
          type: string
          description: Your internal identifier for the facility
          example: FAC-001
        facilityType:
          type: object
          description: Information about the facility type
          $ref: '#/components/schemas/FacilityTypeGet'
        organization:
          type: object
          description: Information about the organization that owns the facility
          $ref: '#/components/schemas/OrganizationGet'
        country:
          type: object
          description: Country where the facility is located (ISO 3166-1 alpha-2)
          $ref: '#/components/schemas/CountryGet'
        region:
          type: object
          description: Region/state where the facility is located
          $ref: '#/components/schemas/RegionGet'
        countrySub:
          type: object
          description: Subdivision of the country where the facility is located
          $ref: '#/components/schemas/CountrySubGet'
        tags:
          items:
            type: string
          type: array
          description: Array of tags associated with the facility
          example:
          - manufacturing
          - primary
        facilityName:
          type: string
          description: The name of the facility
          example: Large Factory
        addressLine1:
          type: string
          description: The first line of the facility address
          example: 123 Main Street
        addressLine2:
          type: string
          description: The second line of the facility address
          example: Suite 100
        city:
          type: string
          description: City where the facility is located
          example: New York
        regionCode:
          type: string
          description: The region/state code
          example: NY
        ownershipType:
          enum:
          - shared
          - standalone
          - standalone_tracked
          - area
          type: string
          description: The ownership type of the facility
        capacityUnit:
          type: string
          description: Unit of measurement for capacity
          example: m2
        capacity:
          type: number
          description: Capacity of the facility
          example: 1000
        employeeCount:
          type: number
          description: Number of employees at the facility
          example: 150
        isOpen:
          type: boolean
          description: Whether the facility is currently open
          example: true
        effectiveDate:
          type: string
          description: Date when this facility version becomes effective
          example: '2025-01-01'
        endDate:
          type: string
          description: Date when this facility version ends
          example: '2025-12-31'
        parentId:
          format: uuid
          type: string
          description: The UUID of the parent facility
          example: eff8f526-4c6a-4ea5-b740-4762aac0469a
        postalCode:
          type: string
          description: Postal code of the facility
          example: '12345'
        versionId:
          format: uuid
          type: string
          description: The UUID of the facility version record
          example: bdd8f526-4c6a-4ea5-b740-4762aac04697
      type: object
      required:
      - versions
      - facilityId
      - internalId
      - facilityType
      - organization
      - country
      - region
      - countrySub
      - tags
      - facilityName
      - addressLine1
      - addressLine2
      - city
      - regionCode
      - ownershipType
      - capacityUnit
      - capacity
      - employeeCount
      - isOpen
      - effectiveDate
      - endDate
      - parentId
      - postalCode
    UpdatableFacilityVersionDTO:
      properties:
        buId:
          format: uuid
          type: string
          description: The UUID of the business unit
          example: dff8f526-4c6a-4ea5-b740-4762aac04699
        name:
          type: string
          description: The name of the facility
          example: Large Factory
        hasAddress:
          type: boolean
          description: Whether the facility has an address
          example: true
        addressLine1:
          type: string
          description: First line of the facility address
          example: 123 Main Street
        addressLine2:
          type: string
          description: Second line of the facility address
          example: Suite 100
        postalCode:
          type: string
          description: Postal code of the facility
          example: '12345'
        city:
          minLength: 1
          type: string
          description: City where the facility is located
          example: New York
        country:
          type: string
          description: Country where the facility is located (ISO 3166-1 alpha-2)
          example: US
        countrySub:
          minLength: 1
          type: string
          description: Subdivision of the country where the facility is located
          example: US-NY
        capacity:
          minimum: 0
          type: number
          description: Capacity of the facility
          example: 1000
        employeeCount:
          minimum: 0
          type: integer
          description: Number of employees at the facility
          example: 150
        boundaryIndicator:
          enum:
          - OPERATIONAL_CONTROL
          - SUPPLIER
          - UPSTREAM_TRANSPORT_AND_DISTRIBUTION
          - UPSTREAM_LEASED
          - DOWNSTREAM_TRANSPORT_AND_DISTRIBUTION
          - PROCESSING_OF_SOLD_PRODUCTS
          - DOWNSTREAM_LEASED
          - FRANCHISE
          - INVESTMENT
          type: string
          description: The boundary indicator for the facility
          example: OPERATIONAL_CONTROL
        isOpen:
          type: boolean
          description: Whether the facility is currently open
          example: true
        effectiveDate:
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d+Z?
          type: string
          description: Date when this facility version becomes effective
          example: '2025-01-01'
      type: object
      required:
      - buId
      - name
      - hasAddress
    OrganizationGet:
      properties:
        id:
          format: uuid
          type: string
          description: The UUID of the organization
          example: dff8f526-4c6a-4ea5-b740-4762aac04699
        name:
          type: string
          description: The name of the organization
          example: Acme Corporation
      type: object
      required:
      - id
      - name
    AreasGet:
      properties:
        facilityId:
          format: uuid
          type: string
          description: The UUID of the facility record
          example: aee349fd-28e4-450d-9e20-af64d9c0d813
        internalId:
          type: string
          description: Your internal identifier for the facility
          example: FAC-001
        facilityType:
          type: object
          description: Information about the facility type
          $ref: '#/components/schemas/FacilityTypeGet'
        organization:
          type: object
          description: Information about the organization that owns the facility
          $ref: '#/components/schemas/OrganizationGet'
        country:
          type: object
          description: Country where the facility is located (ISO 3166-1 alpha-2)
          $ref: '#/components/schemas/CountryGet'
        region:
          type: object
          description: Region/state where the facility is located
          $ref: '#/components/schemas/RegionGet'
        countrySub:
          type: object
          description: Subdivision of the country where the facility is located
          $ref: '#/components/schemas/CountrySubGet'
        tags:
          items:
            type: string
          type: array
          description: Array of tags associated with the facility
          example:
          - manufacturing
          - primary
        facilityName:
          type: string
          description: The name of the facility
          example: Large Factory
        addressLine1:
          type: string
          description: The first line of the facility address
          example: 123 Main Street
        addressLine2:
          type: string
          description: The second line of the facility address
          example: Suite 100
        city:
          type: string
          description: City where the facility is located
          example: New York
        ownershipType:
          enum:
          - shared
          - standalone
          - standalone_tracked
          - area
          type: string
          description: The ownership type of the facility
        capacityUnit:
          type: string
          description: Unit of measurement for capacity
          example: m2
        capacity:
          type: number
          description: Capacity of the facility
          example: 1000
        employeeCount:
          type: number
          description: Number of employees at the facility
          example: 150
        isOpen:
          type: boolean
          description: Whether the facility is currently open
          example: true
        effectiveDate:
          type: string
          description: Date when this facility version becomes effective
          example: '2025-01-01'
        endDate:
          type: string
          description: Date when this facility version ends
          example: '2025-12-31'
        parentId:
          format: uuid
          type: string
          description: The UUID of the parent facility
          example: eff8f526-4c6a-4ea5-b740-4762aac0469a
        versionId:
          format: uuid
          type: string
          description: The UUID of the facility version record
          example: bdd8f526-4c6a-4ea5-b740-4762aac04697
      type: object
      required:
      - facilityId
      - internalId
      - facilityType
      - organization
      - country
      - region
      - countrySub
      - tags
      - facilityName
      - addressLine1
      - addressLine2
      - city
      - ownershipType
      - capacityUnit
      - capacity
      - employeeCount
      - isOpen
      - effectiveDate
      - endDate
      - parentId
      - versionId
    FacilityTypePublicGet:
      properties:
        id:
          format: uuid
          type: string
          description: The UUID of the facility type
          example: cff8f526-4c6a-4ea5-b740-4762aac04698
        name:
          type: string
          description: The name of the facility type
          example: Manufacturing Plant
      type: object
      required:
      - id
      - name
    FacilitiesGet:
      properties:
        areas:
          items:
            type: object
            $r

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/altruistiq/refs/heads/main/openapi/altruistiq-facility-api-openapi.yml