Tidelift Projects API

openapi: 3.0.0
info:
  version: 1.2.1
  title: Tidelift External Alignments Projects API
  x-logo:
    url: /docs/assets/tidelift_logo.png
    altText: Tidelift
  license:
    name: Proprietary
servers:
- url: https://api.tidelift.com/external-api
security:
- BearerAuth:
  - user
  - project
  - organization
tags:
- name: Projects
paths:
  /v1/{org_name}/projects:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - organization
      operationId: listProjects
      x-rails-controller: projects#index
      summary: List organization projects
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      responses:
        '200':
          description: A list of projects in the Organization
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - projects
                properties:
                  projects:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Project'
                      - type: object
                        properties:
                          created_at:
                            type: string
                            format: date-time
                            description: When the project was created
        '401':
          $ref: '#/components/responses/401Error'
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - organization
      operationId: createProject
      x-rails-controller: projects#create
      summary: Create a new project
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                groups:
                  type: array
                  description: List of group slugs or names to associate the project with
                  items:
                    type: string
                catalog:
                  type: string
                  description: Catalog to align to. Required if mulitple catalogs are in use
                project_name:
                  type: string
                default_branch:
                  type: string
                external_identifier:
                  type: string
                  description: An optional custom identifier that can be set that corresponds to something outside of Tidelift
              required:
              - project_name
      responses:
        '201':
          description: Project that was created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Project'
                - type: object
                  additionalProperties: false
                  required:
                  - using_catalog
                  - dot_tidelift
                  properties:
                    using_catalog:
                      type: string
                      nullable: true
                    dot_tidelift:
                      type: string
        '400':
          description: The project name, external identifier, branch name, groups or catalog are invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  available_catalogs:
                    type: array
                    deprecated: true
                    items:
                      type: string
                  details:
                    type: object
                    properties:
                      available_catalogs:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403GroupUsers'
  /v1/{org_name}/projects/{project}:
    delete:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - organization
      operationId: deleteProject
      x-rails-controller: projects#destroy
      summary: Delete a project.
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/projectParam'
      responses:
        '200':
          description: The project is deleted
        '403':
          $ref: '#/components/responses/403GroupUsers'
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - project
        - organization
      operationId: updateProject
      x-rails-controller: projects#update
      summary: Update project details
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/projectParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Project'
              - type: object
                additionalProperties: false
                required:
                - catalog
                properties:
                  catalog:
                    type: string
                    nullable: true
      responses:
        '200':
          description: Successfully updated project details
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403GroupUsers'
        '404':
          description: Invalid catalog or groups sent
  /v1/{org_name}/projects/{project}/new-key:
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - project
        - organization
      operationId: createProjectKey
      x-rails-controller: projects#create_project_key
      summary: Create a new project API key
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/projectParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the key being created
      responses:
        '201':
          description: The token generated for the key
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - key
                properties:
                  key:
                    type: string
                    description: The token assigned to the created key
        '401':
          $ref: '#/components/responses/401Error'
  /v1/{org_name}/projects/import-sbom:
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - project
        - organization
      operationId: importSbomProject
      x-rails-controller: projects#import_sbom
      summary: Create a new project with an initial scan, using the provided SBOM file as the manifest.
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 'An SBOM file of type: SPDX tag/value, CycloneDX JSON or CycloneDX XML.'
                project_name:
                  type: string
                  description: Can be used to set project name if a name is not detected in the SBOM file.
                groups:
                  type: array
                  description: List of group slugs or names to associate the project with
                  items:
                    type: string
                catalog:
                  type: string
                  description: Catalog to align to. Required if mulitple catalogs are in use
              required:
              - file
      responses:
        '201':
          description: Project that was created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Project'
                - type: object
                  additionalProperties: false
                  properties:
                    using_catalog:
                      type: string
                      nullable: true
                    dot_tidelift:
                      type: string
                    attestation_report_url:
                      type: string
        '400':
          description: The project name, groups, catalog or SBOM file are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403GroupUsers'
  /v1/{org_name}/projects/{project}/attestation-report:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - project
        - organization
      operationId: getAttestationReport
      x-rails-controller: projects#attestation_report
      summary: Get the TACOS-formatted attestation report for packages used in a project
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/projectParam'
      - name: revision
        required: false
        in: query
        description: sha revision of the project scan for which to download the attestation report (if not provided will use the latest scan of the project's default branch)
        schema:
          type: string
      responses:
        '200':
          description: The attestation report
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - '@id'
                - location
                - author
                - role
                - LastModifiedDateTimeUTC
                - TACOSversion
                - application
                - statements
                properties:
                  '@id':
                    type: string
                    description: the TACOS framework URL (https://github.com/tacosframework)
                  location:
                    type: string
                    description: URL of this attestation report
                  author:
                    type: string
                    description: the author of the report (Tidelift Support)
                  role:
                    type: string
                    description: the role of the author (Attestor)
                  LastModifiedDateTimeUTC:
                    type: string
                    description: timestamp of the report's creation
                  TACOSversion:
                    type: string
                    description: the version of TACOS used to generate the report
                  application:
                    type: string
                    description: the name of the project for which the report was generated
                  statements:
                    type: array
                    items:
                      type: object
                      description: a hash of TACOS statements (https://github.com/tacosframework/TACOS-spec) and their values at time of report generation
        '400':
          description: project not found, or scan not found, or attestation report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '401':
          $ref: '#/components/responses/401Error'
  /v1/catalog/{org_name}/{project}/bill-of-materials:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Projects
      security:
      - BearerAuth:
        - user
        - project
        - organization
      operationId: getProjectBillOfMaterials
      x-rails-controller: projects#bill_of_materials
      summary: Get a project's bill of materials
      description: "Get the bill of materials for the latest alignment or, optionally, a specific alignment for the project based on the revision or alignment id.\n\nTo request an bill of materials, both a file format and SBOM type must be specified.\n\nThe file format can be specified in several ways:\n  * using the `format` query parameter\n  * using the `Accept` header\n  * using a file extension on the route (e.g. sbom.json to request the JSON file format).\n\nThe SBOM type can be specified using the `sbom_type` query parameter.\n\nSupported combinations:\n  * `format=json, sbom_type=tidelift`: generic Tidelift JSON bill of materials\n    * This format will also be used if both `format` and `sbom_type` are omitted\n  * `format=json`, `sbom_type=cyclonedx`\n  * `format=csv, sbom_type=tidelift`: generic Tidelift CSV bill of materials\n    * This format will also be used if `sbom_type` is omitted\n  * `format=xml`, `sbom_type=cyclonedx`\n  * `format=spdx`, `sbom_type=spdx`\n    * for SPDX, only specifying `format` is necessary, `sbom_type` can be inferred\n\nOlder versions of the API supported using only the `format` query parameter (without also specifying an `sbom_type`).\nThe following mappings are provided to maintain backwards compatibility.\n  * `format=cyclonedx` or `format=cyclone_dx` implies `format=xml` and `sbom_type=cyclonedx`.\n  * `format=spdx` also implies `sbom_type=spdx`\n"
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - name: project
        in: path
        required: true
        schema:
          type: string
      - name: revision
        in: query
        required: false
        description: Revision id of the alignment to lookup
        schema:
          type: string
      - name: alignment_id
        in: query
        required: false
        description: Id of the alignment to lookup
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - csv
          - spdx
          - xml
          example: json
          description: Determines the file format the BoM data is formatted in. Defaults to a JSON format. Legacy values are supported here, for example `cyclonedx` will default to `xml`.
      - name: sbom_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - tidelift
          - cyclonedx
          - spdx
          description: Determines the BoM format to use to for the data.
      responses:
        '200':
          description: Bill of materials for a given alignment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillOfMaterials'
        '401':
          $ref: '#/components/responses/401Error'
        '400':
          $ref: '#/components/responses/400Error'
        '404':
          description: Couldn't find scan by revision or latest from default branch, or unable to build BOM from Scan.
components:
  schemas:
    StandardError:
      description: The standard error format
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: An error code representing the error
          example: an_error_code
        message:
          type: string
          description: A human-readable error message representing the error
          example: An error message.
        details:
          type: object
          description: An optional object with extra helpful details about the error.
          example:
            errors:
              name: is not a valid email.
    BillOfMaterials:
      type: array
      items:
        type: object
        additionalProperties: false
        required:
        - name
        - platform
        - version
        - license_analysis
        - direct
        - sources
        properties:
          name:
            type: string
          platform:
            type: string
          version:
            type: string
          license_analysis:
            type: object
            properties:
              platform:
                type: string
              name:
                type: string
              version:
                type: string
              license:
                type: string
              source:
                type: string
                nullable: true
              original_license:
                type: string
                nullable: true
              status:
                type: string
          direct:
            type: boolean
          sources:
            type: array
            items:
              type: object
              properties:
                type:
                  type: string
                kind:
                  type: string
                requirement:
                  type: string
                path:
                  type: string
    Project:
      type: object
      additionalProperties: false
      required:
      - name
      - groups
      - branching_behavior
      - default_branch
      - external_identifier
      properties:
        name:
          type: string
        catalog:
          type: string
        groups:
          type: array
          description: List of group slugs associated with the project
          items:
            type: string
          nullable: true
        branching_behavior:
          type: string
          enum:
          - specified_branch
          - latest_aligned_branch
          description: 'Controls how the project''s default branch is determined. `specified_branch` uses the branch set in `default_branch`. `latest_aligned_branch` automatically updates to the most recently aligned branch.

            '
        default_branch:
          type: string
        external_identifier:
          type: string
          description: An optional custom identifier that can be set that corresponds to something outside of Tidelift
          nullable: true
  parameters:
    orgNameParam:
      in: path
      name: org_name
      required: true
      schema:
        type: string
        example: My-Company
      description: The name of the Organization.
    projectParam:
      in: path
      name: project
      required: true
      schema:
        type: string
      description: The name of the Project.
  responses:
    400Error:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardError'
    401Error:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardError'
    403GroupUsers:
      description: The user is not an admin of the organization or doesn't belong to the organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer