> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lukittu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Releases

> Retrieve a paginated list of releases for a specific product within the team.
Results can be filtered by version search and release status.




## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/dev/teams/{teamId}/releases
openapi: 3.0.1
info:
  title: Lukittu API
  description: >
    The Lukittu API provides comprehensive license management and verification
    services for software products.


    ## Authentication


    **Client Endpoints** (`/api/v1/client/*`): No authentication required. These
    are public endpoints for license verification.


    **Developer Endpoints** (`/api/v1/dev/*`): Require API key authentication
    via Bearer token.


    ## API Types


    - **Client API**: Used by your software to verify licenses, send heartbeats,
    and download releases

    - **Developer API**: Used for programmatic license management from your
    backend systems


    ## Rate Limiting


    All endpoints are rate-limited to prevent abuse. If you exceed the rate
    limit, you'll receive a 429 status code.


    ## Response Format


    All responses follow a consistent format with `data` and `result` objects:


    ```json

    {
      "data": {}, // Response data (null for errors)
      "result": {
        "timestamp": "2023-09-15T14:30:00Z",
        "valid": true,
        "details": "Human-readable message",
        "code": "SUCCESS_CODE" // Optional error/success code
      }
    }

    ```
  version: 1.0.0
  contact:
    name: Lukittu Community
    url: https://discord.lukittu.com
servers:
  - url: https://app.lukittu.com
    description: Production server
security: []
tags:
  - name: Client - Verify
    description: >
      Client endpoints for license verification, heartbeat monitoring, and file
      downloads.

      These endpoints are used directly by your software applications.
  - name: Dev - Licenses
    description: |
      Developer endpoints for license management operations.
      These endpoints require API key authentication.
  - name: Dev - Customers
    description: |
      Developer endpoints for customer management operations.
      These endpoints require API key authentication.
  - name: Dev - Releases
    description: |
      Developer endpoints for release management operations.
      These endpoints require API key authentication.
  - name: Dev - Statistics
    description: |
      Developer endpoints for retrieving team usage statistics.
      These endpoints require API key authentication.
paths:
  /api/v1/dev/teams/{teamId}/releases:
    get:
      tags:
        - Dev - Releases
      summary: List Releases
      description: >
        Retrieve a paginated list of releases for a specific product within the
        team.

        Results can be filtered by version search and release status.
      operationId: listReleases
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/SortDirection'
        - name: productId
          in: query
          required: true
          description: UUID of the product to list releases for
          schema:
            $ref: '#/components/schemas/UUID'
          example: 789e0123-e89b-12d3-a456-426614174222
        - name: sortColumn
          in: query
          required: false
          description: Column to sort by
          schema:
            type: string
            enum:
              - version
              - createdAt
              - updatedAt
              - latest
            default: createdAt
          example: createdAt
        - name: search
          in: query
          required: false
          description: Search releases by version (case-insensitive partial match)
          schema:
            type: string
          example: '1.0'
        - name: status
          in: query
          required: false
          description: Filter releases by status
          schema:
            $ref: '#/components/schemas/ReleaseStatus'
          example: PUBLISHED
      responses:
        '200':
          description: Releases retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
              example:
                data:
                  releases:
                    - id: 456e7890-e89b-12d3-a456-426614174111
                      version: 1.0.0
                      status: PUBLISHED
                      latest: true
                      productId: 789e0123-e89b-12d3-a456-426614174222
                      branchId: null
                      teamId: 123e4567-e89b-12d3-a456-426614174000
                      createdAt: '2023-09-15T14:30:00Z'
                      updatedAt: '2023-09-15T14:30:00Z'
                      metadata: []
                      product:
                        id: 789e0123-e89b-12d3-a456-426614174222
                        name: My Product
                      branch: null
                      file: null
                      allowedLicenses: []
                  hasNextPage: false
                  totalResults: 1
                result:
                  timestamp: '2023-09-15T14:30:00Z'
                  valid: true
                  details: Releases found
        4XX:
          $ref: '#/components/responses/StandardError'
        5XX:
          $ref: '#/components/responses/StandardError'
      security:
        - bearerAuth: []
components:
  parameters:
    TeamId:
      name: teamId
      in: path
      required: true
      description: >-
        Your team's UUID. You can find this value in your team's settings on the
        Lukittu dashboard.
      schema:
        $ref: '#/components/schemas/UUID'
      example: 123e4567-e89b-12d3-a456-426614174000
    Page:
      name: page
      in: query
      required: false
      description: Page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    PageSize:
      name: pageSize
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        enum:
          - 10
          - 25
          - 50
          - 100
        default: 25
      example: 25
    SortDirection:
      name: sortDirection
      in: query
      required: false
      description: Sort direction
      schema:
        type: string
        enum:
          - asc
          - desc
        default: desc
      example: desc
  schemas:
    UUID:
      type: string
      format: uuid
      description: UUID v4 identifier
    ReleaseStatus:
      type: string
      enum:
        - PUBLISHED
        - DRAFT
        - ARCHIVED
        - DEPRECATED
      description: Status of a product release
    ReleaseListResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                releases:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/ReleaseData'
                      - type: object
                        properties:
                          metadata:
                            $ref: '#/components/schemas/Metadata'
                          product:
                            $ref: '#/components/schemas/ProductData'
                          branch:
                            type: object
                            nullable: true
                            properties:
                              id:
                                $ref: '#/components/schemas/UUID'
                              name:
                                type: string
                          file:
                            $ref: '#/components/schemas/ReleaseFileData'
                          allowedLicenses:
                            type: array
                            items:
                              $ref: '#/components/schemas/LicenseData'
                hasNextPage:
                  type: boolean
                  description: Whether more pages are available
                totalResults:
                  type: integer
                  description: Total number of matching releases
              required:
                - releases
                - hasNextPage
                - totalResults
    SuccessResponse:
      type: object
      properties:
        data:
          type: object
          description: Response data
        result:
          allOf:
            - $ref: '#/components/schemas/StandardResult'
            - type: object
              properties:
                valid:
                  type: boolean
                  enum:
                    - true
                  description: Always true for success responses
      required:
        - data
        - result
    ReleaseData:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        version:
          $ref: '#/components/schemas/Version'
        status:
          $ref: '#/components/schemas/ReleaseStatus'
        latest:
          type: boolean
          description: Whether this is the latest release for the product/branch
        productId:
          $ref: '#/components/schemas/UUID'
        branchId:
          $ref: '#/components/schemas/UUID'
          nullable: true
          description: Branch this release belongs to
        teamId:
          $ref: '#/components/schemas/UUID'
          description: Team that owns this release
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - version
        - status
        - latest
        - productId
        - teamId
        - createdAt
        - updatedAt
    Metadata:
      type: array
      description: Key-value metadata pairs
      items:
        type: object
        properties:
          key:
            type: string
            description: Metadata key
          value:
            type: string
            description: Metadata value
          locked:
            type: boolean
            description: Whether this metadata field is locked from client modification
        required:
          - key
          - value
          - locked
    ProductData:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: Unique product identifier
        name:
          type: string
          description: Product name
        url:
          type: string
          nullable: true
          description: Product URL or homepage
        metadata:
          $ref: '#/components/schemas/Metadata'
        teamId:
          $ref: '#/components/schemas/UUID'
          description: Team that owns this product
        createdByUserId:
          $ref: '#/components/schemas/UUID'
          description: User who created this product
        createdAt:
          type: string
          format: date-time
          description: Product creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Product last update timestamp
      required:
        - id
        - name
        - teamId
        - createdByUserId
        - createdAt
        - updatedAt
    ReleaseFileData:
      type: object
      nullable: true
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        key:
          type: string
          description: S3 storage key
        size:
          type: integer
          description: File size in bytes
        name:
          type: string
          description: Original file name
        checksum:
          type: string
          description: MD5 checksum of the file
        mainClassName:
          type: string
          nullable: true
          description: Main class name (for JAR files)
      required:
        - id
        - key
        - size
        - name
        - checksum
    LicenseData:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: Unique license identifier
        licenseKey:
          $ref: '#/components/schemas/LicenseKey'
        ipLimit:
          type: integer
          nullable: true
          minimum: 0
          description: Maximum number of different IP addresses that can use this license
        hwidLimit:
          type: integer
          nullable: true
          minimum: 1
          description: Maximum number of different hardware IDs that can use this license
        expirationType:
          $ref: '#/components/schemas/ExpirationType'
        expirationStart:
          $ref: '#/components/schemas/ExpirationStart'
        expirationDate:
          type: string
          format: date-time
          nullable: true
          description: Specific expiration date (when expirationType is DATE)
        expirationDays:
          type: integer
          nullable: true
          minimum: 1
          description: Number of days until expiration (when expirationType is DURATION)
        suspended:
          type: boolean
          description: Whether the license is suspended
        metadata:
          $ref: '#/components/schemas/Metadata'
        teamId:
          $ref: '#/components/schemas/UUID'
          description: Team that owns this license
        createdByUserId:
          $ref: '#/components/schemas/UUID'
          description: User who created this license
        createdAt:
          type: string
          format: date-time
          description: License creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: License last update timestamp
        lastActiveAt:
          type: string
          format: date-time
          nullable: true
          description: Last activity timestamp for this license
      required:
        - id
        - licenseKey
        - expirationType
        - suspended
        - teamId
        - createdByUserId
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        data:
          type: object
          description: Additional error-related data
          nullable: true
        result:
          allOf:
            - $ref: '#/components/schemas/StandardResult'
            - type: object
              properties:
                valid:
                  type: boolean
                  enum:
                    - false
                  description: Always false for error responses
                code:
                  type: string
                  description: Error code indicating the specific issue
                  enum:
                    - INTERNAL_SERVER_ERROR
                    - BAD_REQUEST
                    - LICENSE_NOT_FOUND
                    - IP_LIMIT_REACHED
                    - HWID_LIMIT_REACHED
                    - PRODUCT_NOT_FOUND
                    - CUSTOMER_NOT_FOUND
                    - LICENSE_EXPIRED
                    - LICENSE_SUSPENDED
                    - TEAM_NOT_FOUND
                    - RATE_LIMIT
                    - HARDWARE_IDENTIFIER_BLACKLISTED
                    - COUNTRY_BLACKLISTED
                    - IP_BLACKLISTED
                    - RELEASE_NOT_FOUND
                    - FORBIDDEN
                    - UNAUTHORIZED
                    - INVALID_SESSION_KEY
                    - NO_ACCESS_TO_RELEASE
                    - RELEASE_ARCHIVED
                    - RELEASE_DRAFT
              required:
                - code
      required:
        - result
    StandardResult:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the response was generated
        valid:
          type: boolean
          description: Indicates whether the operation was successful
        details:
          type: string
          description: Human-readable description of the result
      required:
        - timestamp
        - valid
        - details
    Version:
      type: string
      minLength: 3
      maxLength: 255
      pattern: ^[^\s]+$
      description: Software version identifier (no spaces allowed)
    LicenseKey:
      type: string
      pattern: ^[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}$
      description: >-
        Lukittu license key format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX where X is an
        uppercase letter (A-Z) or digit (0-9)
    ExpirationType:
      type: string
      enum:
        - NEVER
        - DATE
        - DURATION
      description: Defines how license expiration is calculated
    ExpirationStart:
      type: string
      enum:
        - CREATION
        - ACTIVATION
      description: Defines when the license expiration countdown begins
  responses:
    StandardError:
      description: >
        Standard API error response. All errors follow the same `{data, result}`
        structure.

        The HTTP status code indicates the general error category, while
        `result.code` provides specific error details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: >
        API key authentication for development endpoints.


        You can create API keys in your team's settings on the Lukittu
        dashboard.

        Include the API key in the Authorization header as: `Bearer
        YOUR_API_KEY`


        Example:

        ```

        Authorization: Bearer lukittu_api_key_abc123def456...

        ```

````