Tidelift Catalogs API

openapi: 3.2.0
info:
  version: 1.2.1
  title: Tidelift External Alignments Catalogs 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: Catalogs
paths:
  /v1/user/catalogs:
    get:
      x-rails-controller: user#catalogs
      summary: List all catalogs and organizations for the user
      operationId: listCatalogsForUser
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      responses:
        '200':
          description: A list of catalogs grouped by organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationWithCatalogs'
        '401':
          $ref: '#/components/responses/401Error'
  /v1/user/catalogs/{org_name}:
    get:
      x-rails-controller: user#catalogs
      summary: List all catalogs for a specific organization
      operationId: listCatalogsForUsersOrg
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      parameters:
      - name: org_name
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A list of catalogs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationWithCatalogs'
        '401':
          $ref: '#/components/responses/401Error'
  /v1/{org_name}/catalogs:
    get:
      x-rails-controller: organization#catalogs
      summary: List all catalogs for an organization
      operationId: listCatalogsForOrg
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - org
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      responses:
        '200':
          description: A list of catalogs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatalogSummary'
        '401':
          $ref: '#/components/responses/401Error'
  /v1/{org_name}/catalogs/{catalog_name}/violations:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
        - organization
      operationId: listViolationsForCatalog
      x-rails-controller: catalog#violations
      summary: Get all the violations for a catalog
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - name: projects[]
        in: query
        required: false
        description: Names of projects to filter by
        schema:
          type: array
          items:
            type: string
          example:
          - my-project
          - my-other-project
      - name: catalog_standards[]
        in: query
        required: false
        description: Filter response to only violations associated with the specified catalog standards. When not provided, no filtering is applied.
        schema:
          type: array
          items:
            type: string
          example:
          - deprecation
          - known_packages
          - up_to_date
          - vulnerabilities
          - allowed_licenses
          - identified_licenses
      - name: has_task
        in: query
        required: false
        description: Filter response to only violations that have an associated task (or not). When not provided, no filtering is applied.
        schema:
          type: boolean
      - name: page
        in: query
        description: Page in results
        schema:
          type: number
      responses:
        '200':
          description: Paginated list of violations for catalog
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginationEnvelope'
                - type: object
                  additionalProperties: false
                  required:
                  - results
                  properties:
                    results:
                      $ref: '#/components/schemas/Violations'
        '404':
          description: Catalog not found, Catalog Standard not found
        '401':
          $ref: '#/components/responses/401Error'
  /v1/{org_name}/catalogs/{catalog_name}/violations/{violation_id}/overrides:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: listViolationStatusOverrides
      x-rails-controller: violation_status_overrides#index
      summary: Gets all overrides for a violation
      description: Gets all overrides for a violation
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - $ref: '#/components/parameters/violationIdParam'
      responses:
        '200':
          description: A list of all overrides for the violation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViolationStatusOverride'
        '404':
          description: 404 Violation Not Found
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: createViolationStatusOverride
      x-rails-controller: violation_status_overrides#create
      summary: Creates a status override for a violation
      description: Creates a status override for a violation. The override can be scoped to a package, a release, or neither
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - $ref: '#/components/parameters/violationIdParam'
      - name: platform
        in: query
        description: The platform of the package, when violation override is scoped to a package or release
        required: false
        schema:
          type: string
      - name: package_name
        in: query
        description: The name of the package, when violation override is scoped to a package or release
        required: false
        schema:
          type: string
      - name: version
        in: query
        description: The version of the package, when violation override is scoped to a release
        required: false
        schema:
          type: string
      - name: note
        in: query
        description: A note that describes the reasoning for the violation override
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: The status that the override will apply to affected releases.
        required: true
        schema:
          type: string
          enum:
          - approved
          - denied
        example: approved
      responses:
        '201':
          description: A response indicating the successful creation of the violation status override
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViolationStatusOverrideId'
        '400':
          description: Invalid parameters
        '401':
          $ref: '#/components/responses/401Error'
  /v1/{org_name}/catalogs/{catalog_name}/violations/{violation_id}/overrides/{violation_status_override_id}:
    delete:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: deleteViolationStatusOverride
      x-rails-controller: violation_status_overrides#destroy
      summary: Deletes a violation status override by ID
      description: Deletes a violation status override by ID
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - $ref: '#/components/parameters/violationIdParam'
      - $ref: '#/components/parameters/violationStatusOverrideIdParam'
      responses:
        '200':
          description: A response indicating the successful deletion of the violation status override
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViolationStatusOverrideId'
        '404':
          description: The Violation status override was not found
  /v1/{org_name}/catalogs/{catalog_name}/blocked_items:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: listCatalogBlockedItems
      x-rails-controller: catalog_blocked_items#index
      summary: Gets all of a catalog's blocked items
      description: Gets all of a catalog's blocked items
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - name: page
        in: query
        description: Page in results
        schema:
          type: number
      - name: per_page
        in: query
        description: Number of results per page
        schema:
          type: number
      responses:
        '200':
          description: A list of a catalog's blocked items
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginationEnvelope'
                - type: object
                  additionalProperties: false
                  required:
                  - results
                  properties:
                    results:
                      type: array
                      items:
                        type: object
                        required:
                        - id
                        - platform
                        - name
                        - version
                        - reason
                        - created_by
                        - created_at
                        properties:
                          id:
                            type: string
                          platform:
                            type: string
                          name:
                            type: string
                          version:
                            type:
                            - string
                            - 'null'
                          reason:
                            type: string
                            description: Notes describing why an item was added to the blocked list
                          created_by:
                            type: string
                            description: The user that added the item to the blocked list
                          created_at:
                            type: string
                            format: date
                            description: When the item was added to the blocked list
        '400':
          description: Invalid parameters
        '403':
          $ref: '#/components/responses/403GroupUsers'
        '404':
          description: Catalog or organization not found
    post:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: createCatalogBlockedItems
      x-rails-controller: catalog_blocked_items#create
      summary: Create catalog blocked items from a version range
      description: Create catalog blocked items from a version range
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                platform:
                  type: string
                name:
                  type: string
                version_low:
                  type:
                  - string
                  - 'null'
                  description: The version low
                version_high:
                  type:
                  - string
                  - 'null'
                  description: The version high
                reason:
                  type: string
                  description: Notes describing why the item was added to the blocked list
              required:
              - platform
              - name
              - reason
      responses:
        '201':
          description: A response indicating the successful creation of a catalog blocked item
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    items:
                      type: string
        '400':
          description: Invalid parameters
        '403':
          $ref: '#/components/responses/403GroupUsers'
        '404':
          description: Catalog or organization not found
  /v1/{org_name}/catalogs/{catalog_name}/blocked_items/{catalog_blocked_item_id}:
    delete:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
      operationId: deleteCatalogBlockedItems
      x-rails-controller: catalog_blocked_items#destroy
      summary: Deletes a catalog blocked item by ID
      description: Deletes a catalog blocked item by ID
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - $ref: '#/components/parameters/catalogBlockedItemIdParam'
      responses:
        '200':
          description: A response indicating the successful deletion of the catalog blocked item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogBlockedItemId'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403GroupUsers'
        '404':
          description: Catalog, organization, or catalog blocked item not found
  /v1/{org_name}/catalogs/{catalog_name}/reports/{report_type}:
    get:
      x-tidelift-api-meta:
        product-area: management-api
        access-level: small
        visibility: public
      tags:
      - Catalogs
      security:
      - BearerAuth:
        - user
        - organization
      operationId: latestCatalogReport
      x-rails-controller: catalog_reports#latest
      summary: Get the latest catalog report
      parameters:
      - $ref: '#/components/parameters/orgNameParam'
      - $ref: '#/components/parameters/catalogNameParam'
      - $ref: '#/components/parameters/reportTypeParam'
      responses:
        '200':
          description: Returns latest catalog report JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  report_type:
                    $ref: '#/components/schemas/ReportTypes'
                  catalog_id:
                    type: string
                  created_at:
                    type: string
                  report:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/ReleaseUsageReport'
                      - $ref: '#/components/schemas/LicenseAttributionReport'
                      - $ref: '#/components/schemas/AllProjectsComplianceReport'
                      - $ref: '#/components/schemas/AllProjectsViolationsReport'
                      - $ref: '#/components/schemas/AllProjectsPackageQualityReport'
                      - $ref: '#/components/schemas/CatalogActivityAuditReport'
                      - $ref: '#/components/schemas/EOLImpactReport'
        '204':
          description: No report has been generated yet.
        '404':
          description: Multiple catalogs found, please specify one.
components:
  schemas:
    CatalogActivityAuditReport:
      type: object
      properties:
        date:
          type: string
        event_name:
          type: string
        event_details:
          type: string
        user:
          type: string
        event_link:
          type: string
    AllProjectsViolationsReport:
      type: object
      properties:
        project:
          type: string
        external_identifier:
          type: string
        catalog:
          type: string
        groups:
          type: string
        violation_type:
          type: string
        platform:
          type: string
        direct_package:
          type: string
        direct_verison:
          type: string
        direct_purl:
          type: string
        violating_package:
          type: string
        violating_version:
          type: string
        violating_purl:
          type: string
        dependency_chain:
          type: string
        dependency_scope:
          type: string
        action:
          type: string
        action_status:
          type: string
        action_recommendation:
          type: string
        recommended_dependency_chain:
          type: string
        violation_id:
          type: string
        violation_title:
          type: string
        violation_description:
          type: string
        violation_allowed:
          type: boolean
        violation_link:
          type: string
        lifter_recommendation:
          type: string
        report_date:
          type: string
    LifterRecommendationFragment:
      type: object
      additionalProperties: false
      required:
      - id
      - impact_score
      - impact_description
      - real_issue
      - false_positive_reason
      - includes_dev
      - specific_methods_affected
      - specific_methods_description
      - other_conditions
      - other_conditions_description
      - workaround_available
      - workaround_description
      - visibility
      - created_at
      - updated_at
      properties:
        id:
          type: string
        impact_score:
          type:
          - number
          - 'null'
        impact_description:
          type:
          - string
          - 'null'
        real_issue:
          type: boolean
        false_positive_reason:
          type:
          - string
          - 'null'
        includes_dev:
          type:
          - boolean
          - 'null'
        specific_methods_affected:
          type:
          - boolean
          - 'null'
        specific_methods_description:
          type:
          - string
          - 'null'
        other_conditions:
          type:
          - boolean
          - 'null'
        other_conditions_description:
          type:
          - string
          - 'null'
        workaround_available:
          type:
          - boolean
          - 'null'
        workaround_description:
          type:
          - string
          - 'null'
        visibility:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
    IdentifiedLicensesViolation:
      type: object
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - original_license
        - repository_url
        properties:
          original_license:
            type:
            - string
            - 'null'
          repository_url:
            type:
            - string
            - 'null'
    EOLImpactReport:
      type: object
      properties:
        purl:
          type: string
        platform:
          type: string
        package_name:
          type: string
        version_in_use:
          type: string
          description: Version requested in catalog
        latest_stable_version:
          type: string
          description: Latest stable version number of package
        days_out:
          type: string
          description: Number of days between the publish date of latest stable version and version in use
        versions_out:
          type: string
          description: Count of major and minor versions between the latest stable version and version in use
        release_is_not_eol:
          $ref: '#/components/schemas/PackageCheckStatus'
        release_is_not_eol_explanation:
          type: string
          description: The categorical reason this release is or is not considered to be at end of life
          enum:
          - release_is_attested_supported
          - release_is_attested_unsupported
          - release_is_prerelease
          - release_is_assumed_supported
          - release_is_assumed_unsupported
        maintenance_plan:
          type: string
          description: The recent versions supported by maintainer or URL at which they report their maintenance policy
        package_is_not_eol:
          $ref: '#/components/schemas/PackageCheckStatus'
        package_is_not_eol_explanation:
          type: string
          description: The categorical reason this package is or is not considered to be at end of life
          enum:
          - package_is_end_of_life
          - package_has_future_end_of_life
          - package_has_no_known_end_of_life
          - package_repository_is_unmaintained
          - package_is_renamed
          - package_is_unknown
        package_eol_effective_on:
          type: string
          description: Date at which the End of Life takes effect
        package_vuln_count:
          type: string
          description: Count of vulnerabilities affecting package
        release_vuln_count:
          type: string
          description: Count of vulnerabilities affecting release
        project_count:
          type: string
          description: Count of projects used by release
        project_names:
          type: string
          description: Comma separated list of project names used by release
        direct:
          type: string
          description: Returns true if any projects use this package as a direct dependency
          enum:
          - true
          - false
        report_date:
          type: string
          description: Timestamp at which report was generated.
    AllowedLicensesViolation:
      type: object
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        additionalProperties: false
        required:
        - license
        properties:
          license:
            type: string
    UpToDateViolation:
      type: object
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - up_to_date
        properties:
          up_to_date:
            type: object
            additionalProperties: false
            required:
            - release_date
            - days_too_old
            properties:
              release_date:
                type:
                - string
                - 'null'
              days_too_old:
                type:
                - string
                - 'null'
    ReportTypes:
      type: string
      enum:
      - all_projects_compliance
      - all_projects_package_quality
      - all_projects_violations
      - catalog_activity_audit
      - eol_impact
      - license_attribution
      - release_usage
      example: all_projects_violations
    AllProjectsPackageQualityReport:
      type: object
      properties:
        purl:
          type: string
        platform:
          type: string
        package_name:
          type: string
        tidelift_recommendation:
          type: string
        tidelift_recommendation_reasons:
          type: string
        production_projects_count:
          type: string
        non_production_projects_count:
          type: string
        direct_projects_count:
          type: string
        transitive_projects_count:
          type: string
        project_usage_link:
          type: string
        package_link:
          type: string
        report_date:
          type: string
    OrganizationWithCatalogs:
      type: object
      additionalProperties: false
      required:
      - name
      - roles
      - catalogs
      properties:
        name:
          type: string
          description: Organization name
        roles:
          type:
          - array
          - 'null'
          items:
            description: role
            type: string
        catalogs:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CatalogSummary'
            - type: object
              additionalProperties: false
              required:
              - roles
              properties:
                roles:
                  type:
                  - array
                  - 'null'
                  items:
                    description: role
                    type: string
    LicenseAttributionReport:
      type: object
      properties:
        package_name:
          type: string
        package_version:
          type: string
        package_platform:
          type: string
        dependency_type:
          type: string
        detected_license:
          type: string
        license_source:
          type: string
        projects_using:
          type: string
        external_link:
          type: string
        package_link:
          type: string
        license_text:
          type: string
    EOLPackagesViolation:
      type: object
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - eol_package
        properties:
          eol_package:
            type: object
            additionalProperties: true
            required:
            - reason
            - description
            properties:
              reason:
                type:
                - string
                - 'null'
              description:
                type:
                - string
                - 'null'
    AllProjectsComplianceReport:
      type: object
      properties:
        project:
          type: string
        external_identifier:
          type:
          - string
          - 'null'
        catalog:
          type: string
        groups:
          type: string
        alignment:
          type: number
        project_link:
          type: string
        blocked_releases_count:
          type: integer
        low_security_vulnerabilities:
          type: integer
        medium_security_vulnerabilities:
          type: integer
        high_security_vulnerabilities:
          type: integer
        critical_security_vulnerabilities:
          type: integer
        active_release_stream_violations:
          type: integer
        allowed_licenses_violations:
          type: integer
        deprecation_violations:
          type: integer
        identified_licenses_violations:
          type: integer
        known_packages_violations:
          type: integer
        prereleases_violations:
          type: integer
        removed_releases_violations:
          type: integer
        up_to_date_violations:
          type: integer
        vulnerabilities_violations:
          type: integer
        eol_packages_violations:
          type: integer
        known_releases_violations:
          type: integer
        report_date:
          type: string
    ViolationCommon:
      type: object
      required:
      - catalog_standard
      - violation_id
      - title
      additionalProperties: false
      properties:
        catalog_standard:
          type: string
        violation_id:
          type: string
        title:
          type: string
        package_name:
          type: string
        package_platform:
          type: string
        version:
          type: string
        task_id:
          type:
          - string
          - 'null'
    CatalogSummary:
      type: object
      additionalProperties: false
      required:
      - display_name
      - name
      - release_count
      properties:
        display_name:
          type: string
        name:
          type: string
        release_count:
          type: integer
          format: int32
    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.
    CatalogBlockedItemId:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          description: The id of the catalog blocked item
          type: string
    ViolationStatusOverrideId:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          description: The id of the violation status override
          type: string
    VulnerabilitiesViolation:
      type: object
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - vulnerability
        properties:
          vulnerability:
            type: object
            additionalProperties: false
            required:
            - id
            - severity
            - description
            - date
            - url
            - severity_rating
            - epss_percentile
            - epss_probability
            - epss_score
            - known_exploited
            - lifter_recommendations
            properties:
              id:
                type:
                - string
                - 'null'
              severity:
                type:
                - string
                - 'null'
              description:
                type:
                - string
                - 'null'
              date:
                type: string
              url:
                type:
                - string
                - 'null'
              severity_rating:
                type:
                - string
                - 'null'
              epss_percentile:
                type:
                - string
                - 'null'
              epss_probability:
                type:
                - string
                - 'null'
              epss_score:
                type:
                - string
                - 'null'
              known_exploited:
                type:
                - boolean
                - 'null'
              lifter_recommendations:
                type: array
                items:
                  $ref: '#/components/schemas/LifterRecommendationFragment'
    ReleaseUsageReport:
      type: object
      properties:
        package_platform:
          type: string
        package_name:
          type: string
        package_version:
          type: string
        package_status:
          type: string
        license:
          type: string
        date_added:
          type: string
        published_date:
          type:
          - string
          - 'null'
        projects_using:
          type: string
        decision_by_name:
          type: string
        decision_by_email:
          type: string
        internal_package:

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