openapi: 3.2.0
info:
  description: 'This is the OpenAPI spec for Xpansiv Connect API. Documentation: https://developer.xpansiv.com/developer-portal/'
  title: Xpansiv Connect Projects API
  version: 1.0.0-beta
servers:
- url: https://sandbox.preprod.connect.xpansiv.com/app/api/v1
  description: SANDBOX
- url: https://uat.preprod.connect.xpansiv.com/app/api/v1
  description: UAT
- url: https://connect.xpansiv.com/app/api/v1
  description: PROD
security:
- bearerToken: []
tags:
- name: Projects
  description: The Project API allows the user to pull publicly available information about carbon projects registered in the registries that are integrated with Xpansiv Connect. Note - this call has a number of optional fields that the user needs to include if desired in the output.
paths:
  /projects/action/search:
    post:
      operationId: searchProjects
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Include'
      summary: Projects search
      requestBody:
        description: Projects search endpoint
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                upn:
                  type: string
                name:
                  type: string
                country:
                  $ref: '#/components/schemas/Ref.Country'
                status:
                  $ref: '#/components/schemas/Ref.ProjectStatus'
                program:
                  $ref: '#/components/schemas/Ref.CarbonProgram'
                registryAssignedId:
                  type: string
                certification:
                  $ref: '#/components/schemas/Ref.Certification'
      responses:
        '200':
          description: Projects search successfully executed
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Page'
                - type: object
                  properties:
                    content:
                      type: array
                      items:
                        $ref: '#/components/schemas/Project'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - INVALID_REQUEST
                    - INVALID_PROJECT_STATUS
                    - INVALID_PROGRAM
                    - INVALID_COUNTRY
                    - INVALID_CERTIFICATION
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_NUMBER
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Projects
components:
  responses:
    '500':
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    '401':
      description: Not authorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotAuthorizedError'
  schemas:
    ProjectCertification:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Ref.Certification'
        projectCertificationDateRanges:
          type: array
          items:
            type: object
            properties:
              certificationStart:
                type: string
                format: date-time
                description: The project certification start date.
              certificationEnd:
                type: string
                format: date-time
                description: The project certification end date.
    NotAuthorizedError:
      type: object
      properties:
        message:
          type: string
    Ref.CarbonProgram:
      type: string
      description: Ref.Data.CARBON_PROGRAM
    Project:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        required:
        - programs
        properties:
          programs:
            type: array
            items:
              type: object
              title: ProjectProgram
              required:
              - program
              - registryAssignedId
              - status
              - creditType
              - projectType
              properties:
                program:
                  $ref: '#/components/schemas/Ref.CarbonProgram'
                programName:
                  type: string
                  description: Registry name.
                registryAssignedId:
                  type: string
                  description: ID assigned by the registry.
                registryAccountHolderName:
                  type: string
                  description: Name of the registry account holder.
                status:
                  $ref: '#/components/schemas/Ref.ProjectRegistryStatus'
                creditType:
                  $ref: '#/components/schemas/Ref.CreditType'
                projectType:
                  $ref: '#/components/schemas/Ref.ProjectType'
                baselineMethodologies:
                  type: array
                  items:
                    $ref: '#/components/schemas/Ref.BaselineMethodology'
                creditingPeriodBegin:
                  type: string
                  format: date-time
                  description: Begin date for credit reporting.
                creditingPeriodEnd:
                  type: string
                  format: date-time
                  description: End date for credit reporting.
          description:
            type: string
            description: The full description from the registry.
          status:
            $ref: '#/components/schemas/Ref.ProjectStatus'
          country:
            $ref: '#/components/schemas/Ref.Country'
          stateProvince:
            type: string
            description: State or Province
          city:
            type: string
            description: City.
          location:
            $ref: '#/components/schemas/Location'
          annualAverageOffsetQty:
            type: integer
            format: int64
            description: Annual average offset quantity.
          projectCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/ProjectCertification'
          issuanceCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/IssuanceCertification'
    Location:
      title: Resource location
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: Latitude.
        longitude:
          type: number
          format: double
          description: Longitude.
    Page:
      type: object
      required:
      - page
      - size
      - totalPages
      - totalElements
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
    InternalServerError:
      type: object
      properties:
        message:
          type: string
    Ref.ProjectType:
      type: string
      description: The project type. Ref.Data.CARBON_PROJECT_TYPE
    Ref.Country:
      type: string
      description: Ref.Data.COUNTRY
    Ref.ProjectStatus:
      type: string
      description: Ref.Data.PROJECT_STATUS
    Ref.Certification:
      type: string
      description: Certification code. Ref.Data.CARBON_CERTIFICATION
    IssuanceCertification:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Ref.Certification'
        vintageYears:
          type: array
          description: Vintage years.
          items:
            type: integer
            format: int32
    Ref.ProjectRegistryStatus:
      type: string
      description: The registry status of the project. Ref.Data.PROJECT_REGISTRY_STATUS
    Ref.BaselineMethodology:
      type: string
      description: Ref.Data.BASELINE_METHODOLOGY
    Resource:
      type: object
      required:
      - name
      properties:
        id:
          type: integer
          format: int64
          description: The unique XC db identifier for the project or generator.
        upn:
          type: string
          description: 'Universal Project Identifier. The unique identifier assigned by Xpansiv Connect to every resource across all registries that  have integrated with the Xpansiv Connect platform.

            '
        name:
          type: string
          description: The registry assigned name of the project or generator.
    Ref.CreditType:
      type: string
      description: The type of the credit. Ref.Data.CARBON_CREDIT_TYPE
  parameters:
    PageSize:
      name: size
      in: query
      required: false
      schema:
        type: integer
        format: int32
    Include:
      name: include
      description: Comma-separated values from optional response fields
      in: query
      required: false
      schema:
        type: string
    PageNumber:
      name: page
      in: query
      required: false
      schema:
        type: integer
        format: int32
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT