Tidelift Catalogs API

openapi: 3.0.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
                            nullable: true
                          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
                  nullable: true
                  description: The version low
                version_high:
                  type: string
                  nullable: true
                  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:
  parameters:
    orgNameParam:
      in: path
      name: org_name
      required: true
      schema:
        type: string
        example: My-Company
      description: The name of the Organization.
    violationStatusOverrideIdParam:
      in: path
      name: violation_status_override_id
      required: true
      schema:
        type: string
        example: 1992c539-11f0-4f9a-a668-da54e77726a2
      description: the ID of the violation status override to perform the action on.
    catalogNameParam:
      in: path
      name: catalog_name
      required: true
      schema:
        type: string
        example: default
      description: The name of the Catalog.
    violationIdParam:
      in: path
      name: violation_id
      required: true
      schema:
        type: string
        example: 1992c539-11f0-4f9a-a668-da54e77726a2
      description: The id of the violation to perform the action on.
    catalogBlockedItemIdParam:
      in: path
      name: catalog_blocked_item_id
      required: true
      schema:
        type: string
        example: 1992c539-11f0-4f9a-a668-da54e77726a2
      description: The id of the catalog blocked item to perform the action on.
    reportTypeParam:
      in: path
      name: report_type
      required: true
      description: "Type of report\n\n - [all_projects_compliance (compliance of projects to catalog standards)](https://support.tidelift.com/hc/en-us/articles/24885171849236)\n - [all_projects_package_quality (Tidelift recommendations by package)](https://support.tidelift.com/hc/en-us/articles/24971666742932)\n - [all_projects_violations (All projects violations)](https://support.tidelift.com/hc/en-us/articles/24883174701332)\n - catalog_activity_audit (Catalog Activity)\n - eol_impact (End of life)\n - license_attribution (License attribution)\n - release_usage (Catalog-wide open source use)\n"
      schema:
        $ref: '#/components/schemas/ReportTypes'
  schemas:
    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
    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
          nullable: true
        impact_description:
          type: string
          nullable: true
        real_issue:
          type: boolean
        false_positive_reason:
          type: string
          nullable: true
        includes_dev:
          type: boolean
          nullable: true
        specific_methods_affected:
          type: boolean
          nullable: true
        specific_methods_description:
          type: string
          nullable: true
        other_conditions:
          type: boolean
          nullable: true
        other_conditions_description:
          type: string
          nullable: true
        workaround_available:
          type: boolean
          nullable: true
        workaround_description:
          type: string
          nullable: true
        visibility:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
    CatalogActivityAuditReport:
      type: object
      properties:
        date:
          type: string
        event_name:
          type: string
        event_details:
          type: string
        user:
          type: string
        event_link:
          type: string
    OrganizationWithCatalogs:
      type: object
      additionalProperties: false
      required:
      - name
      - roles
      - catalogs
      properties:
        name:
          type: string
          description: Organization name
        roles:
          type: array
          nullable: true
          items:
            description: role
            type: string
        catalogs:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CatalogSummary'
            - type: object
              additionalProperties: false
              required:
              - roles
              properties:
                roles:
                  type: array
                  nullable: true
                  items:
                    description: role
                    type: string
    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
          nullable: true
        projects_using:
          type: string
        decision_by_name:
          type: string
        decision_by_email:
          type: string
        internal_package:
          type: string
        package_link:
          type: string
        package_source:
          type: string
        purl:
          type: string
        deny_at:
          type: string
          nullable: true
    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
    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
    Violations:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/AllowedLicensesViolation'
        - $ref: '#/components/schemas/DeprecationViolation'
        - $ref: '#/components/schemas/EOLPackagesViolation'
        - $ref: '#/components/schemas/IdentifiedLicensesViolation'
        - $ref: '#/components/schemas/UpToDateViolation'
        - $ref: '#/components/schemas/VulnerabilitiesViolation'
    PackageCheckStatus:
      type: string
      enum:
      - passed
      - not_passed
      - noassertion
      - pending
    DeprecationViolation:
      type: object
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - deprecation
        properties:
          deprecation:
            type: object
            additionalProperties: false
            required:
            - deprecated_at
            - reason
            - package_to_use_instead
            properties:
              deprecated_at:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
              package_to_use_instead:
                type: object
                additionalProperties: false
                nullable: true
                required:
                - platform
                - name
                properties:
                  platform:
                    type: string
                  name:
                    type: string
    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.
    IdentifiedLicensesViolation:
      type: object
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/ViolationCommon'
      - type: object
        required:
        - original_license
        - repository_url
        properties:
          original_license:
            type: string
            nullable: true
          repository_url:
            type: string
            nullable: true
    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
          nullable: true
    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
    CatalogBlockedItemId:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          description: The id of the catalog blocked item
          type: string
    ViolationStatusOverride:
      type: array
      items:
        type: object
        additionalProperties: false
        required:
        - id
        - violation_id
        - platform
        - name
        - version
        - status
        - note
        - created_at
        - created_by
        properties:
          id:
            type: string
          catalog_standard:
            type: string
            nullable: true
          violation_id:
            type: string
          platform:
            type: string
            description: The platform of the package, when the VSO is scoped to a package or release
            nullable: true
          name:
            type: string
            description: The name of the package, when the VSO is scoped to a package or release
            nullable: true
          version:
            type: string
            description: The version of the package, when the VSO is scoped to a release
            nullable: true
          note:
            type: string
            nullable: true
          status:
            type: string
            description: The status that this applies to any affected releases.
          created_at:
            type: string
            format: date-time
          created_by:
            type: string
            description: Name of the User that added the override
    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
                nullable: true
              days_too_old:
                type: string
                nullable: true
    PaginationEnvelope:
      type: object
      required:
      - current_page
      - next_page
      - prev_page
      - total_pages
      - total_count
      - per_page
      properties:
        current_page:
          type: integer
        next_page:
          type:

# --- 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