Cloudsmith entitlements API

openapi: 3.2.0
info:
  title: Cloudsmith API (v1) audit-log Entitlements API
  description: The API to the Cloudsmith Service
  termsOfService: https://help.cloudsmith.io
  contact:
    name: Cloudsmith Support
    url: https://help.cloudsmith.io
    email: support@cloudsmith.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: v1
servers:
- url: https://api.cloudsmith.io/
security:
- apikey: []
- basic: []
tags:
- name: entitlements
paths:
  /entitlements/{owner}/{repo}/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: entitlements_list
      summary: Get a list of all entitlements in a repository.
      description: Get a list of all entitlements in a repository.
      parameters:
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      - name: query
        in: query
        description: A search term for querying names of entitlements.
        required: false
        schema:
          type: string
      - name: active
        in: query
        description: If true, only include active tokens
        required: false
        schema:
          type: boolean
          default: false
      - name: sort
        in: query
        description: 'A field for sorting objects in ascending or descending order. Use `-` prefix for descending order (e.g., `-name`). Available options: name.'
        required: false
        schema:
          type: string
          default: name
      responses:
        '200':
          description: Retrieved the list of entitlement tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RepositoryToken'
        '404':
          description: Owner namespace or repository not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
    post:
      operationId: entitlements_create
      summary: Create a specific entitlement in a repository.
      description: Create a specific entitlement in a repository.
      parameters:
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '201':
          description: Created the specified entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryToken'
        '404':
          description: Owner namespace or repository not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryTokenRequest'
  /entitlements/{owner}/{repo}/sync/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_sync
      summary: Synchronise tokens from a source repository.
      description: Synchronise tokens from a source repository.
      parameters:
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The tokens have been synchronised from the source repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryTokenSync'
        '404':
          description: Owner namespace or repository not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryTokenSyncRequest'
  /entitlements/{owner}/{repo}/{identifier}/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: entitlements_read
      summary: Get a specific entitlement in a repository.
      description: Get a specific entitlement in a repository.
      parameters:
      - name: fuzzy
        in: query
        description: If true, entitlement identifiers including name will be fuzzy matched.
        required: false
        schema:
          type: boolean
          default: false
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Retrieved the specified entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryToken'
        '400':
          description: Couldn't retrieve the specified token because the request contains an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Owner namespace or repository not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
    patch:
      operationId: entitlements_partial_update
      summary: Update a specific entitlement in a repository.
      description: Update a specific entitlement in a repository.
      parameters:
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Updated the specified entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryToken'
        '400':
          description: The entitlement cannot be edited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Owner namespace or repository not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryTokenRequestPatch'
    delete:
      operationId: entitlements_delete
      summary: Delete a specific entitlement in a repository.
      description: Delete a specific entitlement in a repository.
      responses:
        '204':
          description: Soft-deleted the specified entitlement token successfully.
        '400':
          description: The entitlement cannot be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
  /entitlements/{owner}/{repo}/{identifier}/disable/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_disable
      summary: Disable an entitlement token in a repository.
      description: Disable an entitlement token in a repository.
      responses:
        '204':
          description: The entitlement token has been disabled.
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
  /entitlements/{owner}/{repo}/{identifier}/enable/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_enable
      summary: Enable an entitlement token in a repository.
      description: Enable an entitlement token in a repository.
      responses:
        '204':
          description: The entitlement token has been enabled.
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
  /entitlements/{owner}/{repo}/{identifier}/refresh/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_refresh
      summary: Refresh an entitlement token in a repository.
      description: Refresh an entitlement token in a repository.
      parameters:
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The entitlement token has been refreshed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryTokenRefresh'
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryTokenRefreshRequest'
  /entitlements/{owner}/{repo}/{identifier}/reset/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_reset
      summary: Reset the statistics for an entitlement token in a repository.
      description: Reset the statistics for an entitlement token in a repository.
      parameters:
      - name: show_tokens
        in: query
        description: Show entitlement token strings in results
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: The entitlement token statistics have been reset.
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
  /entitlements/{owner}/{repo}/{identifier}/toggle-private-broadcasts/:
    parameters:
    - name: owner
      in: path
      required: true
      schema:
        type: string
    - name: repo
      in: path
      required: true
      schema:
        type: string
    - name: identifier
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: entitlements_toggle_private_broadcasts
      summary: Set private broadcast access for an entitlement token in a repository.
      description: Set private broadcast access for an entitlement token in a repository.
      responses:
        '200':
          description: Private broadcasts access has been updated for the entitlement token.
        '400':
          description: Request could not be processed (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Missing or invalid parameters (see detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      tags:
      - entitlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryTokenPrivateBroadcastsRequest'
components:
  schemas:
    RepositoryTokenRequest:
      required:
      - name
      type: object
      properties:
        eula_required:
          title: Eula required
          description: If checked, a EULA acceptance is required for this token.
          type: boolean
        is_active:
          title: Token Active
          description: If enabled, the token will allow downloads based on configured restrictions (if any).
          type: boolean
        limit_bandwidth:
          title: Limit bandwidth
          description: 'The maximum download bandwidth allowed for the token. Values are expressed as the selected unit of bandwidth. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point. '
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_bandwidth_unit:
          title: Limit bandwidth unit
          type:
          - string
          - 'null'
          enum:
          - Byte
          - Kilobyte
          - Megabyte
          - Gigabyte
          - Terabyte
          - Petabyte
          - Exabyte
          - Zettabyte
          - Yottabyte
          default: Byte
        limit_date_range_from:
          title: Limit date range from
          description: The starting date/time the token is allowed to be used from.
          type:
          - string
          - 'null'
          format: date-time
        limit_date_range_to:
          title: Limit date range to
          description: The ending date/time the token is allowed to be used until.
          type:
          - string
          - 'null'
          format: date-time
        limit_num_clients:
          title: Limit num clients
          description: The maximum number of unique clients allowed for the token. Please note that since clients are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_num_downloads:
          title: Limit num downloads
          description: The maximum number of downloads allowed for the token. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_package_query:
          title: Limit package query
          description: The package-based search query to apply to restrict downloads to. This uses the same syntax as the standard search used for repositories, and also supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. This will still allow access to non-package files, such as metadata.
          type:
          - string
          - 'null'
          maxLength: 1024
        limit_path_query:
          title: Limit path query
          description: THIS WILL SOON BE DEPRECATED, please use limit_package_query instead. The path-based search query to apply to restrict downloads to. This supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. The path evaluated does not include the domain name, the namespace, the entitlement code used, the package format, etc. and it always starts with a forward slash.
          type:
          - string
          - 'null'
          maxLength: 1024
        metadata:
          title: Metadata
          type:
          - object
          - 'null'
        name:
          title: Name
          type: string
          minLength: 1
        scheduled_reset_at:
          title: Scheduled reset at
          description: The time at which the scheduled reset period has elapsed and the token limits were automatically reset to zero.
          type:
          - string
          - 'null'
          format: date-time
        scheduled_reset_period:
          title: Scheduled reset period
          type:
          - string
          - 'null'
          enum:
          - Never Reset
          - Daily
          - Weekly
          - Fortnightly
          - Monthly
          - Bi-Monthly
          - Quarterly
          - Every 6 months
          - Annual
          default: Never Reset
        token:
          title: Token
          type: string
          minLength: 1
    RepositoryTokenRefresh:
      type: object
      properties:
        access_private_broadcasts:
          title: Access private broadcasts
          description: If enabled, this token can be used for private broadcasts
          type: boolean
          readOnly: true
        clients:
          title: Clients
          type: integer
          readOnly: true
        created_at:
          title: Created at
          description: The datetime the token was updated at.
          type: string
          format: date-time
          readOnly: true
        created_by:
          title: Created by
          type: string
          readOnly: true
          minLength: 1
        created_by_url:
          title: Created by url
          type: string
          format: uri
          readOnly: true
        default:
          title: Default
          description: If selected this is the default token for this repository.
          type: boolean
          readOnly: true
        disable_url:
          title: Disable url
          type: string
          format: uri
          readOnly: true
        downloads:
          title: Downloads
          type: integer
          readOnly: true
        enable_url:
          title: Enable url
          type: string
          format: uri
          readOnly: true
        eula_accepted:
          $ref: '#/components/schemas/Eula'
        eula_accepted_at:
          title: Eula accepted at
          description: The datetime the EULA was accepted at.
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        eula_accepted_from:
          title: Eula accepted from
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        eula_required:
          title: Eula required
          description: If checked, a EULA acceptance is required for this token.
          type: boolean
        has_limits:
          title: Has limits
          type: boolean
          readOnly: true
        identifier:
          title: Identifier
          description: 'Deprecated (23-05-15): Please use ''slug_perm'' instead. Previously: A monotonically increasing number that identified an entitlement within a repository.'
          type:
          - integer
          - 'null'
          readOnly: true
        is_active:
          title: Token Active
          description: If enabled, the token will allow downloads based on configured restrictions (if any).
          type: boolean
        is_limited:
          title: Is limited
          type: boolean
          readOnly: true
        limit_bandwidth:
          title: Limit bandwidth
          description: 'The maximum download bandwidth allowed for the token. Values are expressed as the selected unit of bandwidth. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point. '
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_bandwidth_unit:
          title: Limit bandwidth unit
          type:
          - string
          - 'null'
          enum:
          - Byte
          - Kilobyte
          - Megabyte
          - Gigabyte
          - Terabyte
          - Petabyte
          - Exabyte
          - Zettabyte
          - Yottabyte
          default: Byte
        limit_date_range_from:
          title: Limit date range from
          description: The starting date/time the token is allowed to be used from.
          type:
          - string
          - 'null'
          format: date-time
        limit_date_range_to:
          title: Limit date range to
          description: The ending date/time the token is allowed to be used until.
          type:
          - string
          - 'null'
          format: date-time
        limit_num_clients:
          title: Limit num clients
          description: The maximum number of unique clients allowed for the token. Please note that since clients are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_num_downloads:
          title: Limit num downloads
          description: The maximum number of downloads allowed for the token. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_package_query:
          title: Limit package query
          description: The package-based search query to apply to restrict downloads to. This uses the same syntax as the standard search used for repositories, and also supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. This will still allow access to non-package files, such as metadata.
          type:
          - string
          - 'null'
          maxLength: 1024
        limit_path_query:
          title: Limit path query
          description: THIS WILL SOON BE DEPRECATED, please use limit_package_query instead. The path-based search query to apply to restrict downloads to. This supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. The path evaluated does not include the domain name, the namespace, the entitlement code used, the package format, etc. and it always starts with a forward slash.
          type:
          - string
          - 'null'
          maxLength: 1024
        metadata:
          title: Metadata
          type:
          - object
          - 'null'
        name:
          title: Name
          type: string
          readOnly: true
          minLength: 1
        refresh_url:
          title: Refresh url
          type: string
          format: uri
          readOnly: true
        reset_url:
          title: Reset url
          type: string
          format: uri
          readOnly: true
        scheduled_reset_at:
          title: Scheduled reset at
          description: The time at which the scheduled reset period has elapsed and the token limits were automatically reset to zero.
          type:
          - string
          - 'null'
          format: date-time
        scheduled_reset_period:
          title: Scheduled reset period
          type:
          - string
          - 'null'
          enum:
          - Never Reset
          - Daily
          - Weekly
          - Fortnightly
          - Monthly
          - Bi-Monthly
          - Quarterly
          - Every 6 months
          - Annual
          default: Never Reset
        self_url:
          title: Self url
          type: string
          format: uri
          readOnly: true
        slug_perm:
          title: Slug perm
          type: string
          format: slug
          pattern: ^[-a-zA-Z0-9_]+$
          readOnly: true
          minLength: 1
        token:
          title: Token
          type: string
          minLength: 1
        updated_at:
          title: Updated at
          description: The datetime the token was updated at.
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        updated_by:
          title: Updated by
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        updated_by_url:
          title: Updated by url
          type:
          - string
          - 'null'
          format: uri
          readOnly: true
        usage:
          title: Usage
          type: string
          readOnly: true
          minLength: 1
        user:
          title: User
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        user_url:
          title: User url
          type:
          - string
          - 'null'
          format: uri
          readOnly: true
    RepositoryTokenSyncRequest:
      required:
      - source
      type: object
      properties:
        source:
          title: Source
          description: The source repository slug (in the same owner namespace).
          type: string
          minLength: 1
    RepositoryTokenRequestPatch:
      type: object
      properties:
        eula_required:
          title: Eula required
          description: If checked, a EULA acceptance is required for this token.
          type: boolean
        is_active:
          title: Token Active
          description: If enabled, the token will allow downloads based on configured restrictions (if any).
          type: boolean
        limit_bandwidth:
          title: Limit bandwidth
          description: 'The maximum download bandwidth allowed for the token. Values are expressed as the selected unit of bandwidth. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point. '
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_bandwidth_unit:
          title: Limit bandwidth unit
          type:
          - string
          - 'null'
          enum:
          - Byte
          - Kilobyte
          - Megabyte
          - Gigabyte
          - Terabyte
          - Petabyte
          - Exabyte
          - Zettabyte
          - Yottabyte
          default: Byte
        limit_date_range_from:
          title: Limit date range from
          description: The starting date/time the token is allowed to be used from.
          type:
          - string
          - 'null'
          format: date-time
        limit_date_range_to:
          title: Limit date range to
          description: The ending date/time the token is allowed to be used until.
          type:
          - string
          - 'null'
          format: date-time
        limit_num_clients:
          title: Limit num clients
          description: The maximum number of unique clients allowed for the token. Please note that since clients are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_num_downloads:
          title: Limit num downloads
          description: The maximum number of downloads allowed for the token. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
          type:
          - integer
          - 'null'
          maximum: 9223372036854775807
          minimum: -9223372036854775808
        limit_package_query:
          title: Limit package query
          description: The package-based search query to apply to restrict downloads to. This uses the same syntax as the standard search used for repositories, and also supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. This will still allow access to non-package files, such as metadata.
          type:
          - string
          - 'null'
          maxLength: 1024
        limit_path_query:
          title: Limit path query
          description: THIS WILL SOON BE DEPRECATED, please use limit_package_query instead. The path-based search query to apply to restrict downloads to. This supports boolean

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