openapi: 3.0.3
info:
  title: Timoni Module Registry Artifacts Modules API
  description: Timoni is a package manager for Kubernetes powered by CUE that provides type-safe alternatives to Helm charts. Timoni modules are distributed as OCI artifacts in container registries. This API describes the OCI registry operations used for module distribution, versioning, and artifact management within the Timoni ecosystem.
  version: v1
  contact:
    name: Timoni Documentation
    url: https://timoni.sh/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://ghcr.io
  description: GitHub Container Registry (default for Timoni modules)
tags:
- name: Modules
  description: Timoni module management and distribution
paths:
  /v2/{registry}/{module}/tags/list:
    get:
      operationId: listModuleTags
      summary: List Module Tags
      description: List all available version tags for a Timoni module in the OCI registry. Returns all published versions using semantic versioning.
      tags:
      - Modules
      parameters:
      - name: registry
        in: path
        required: true
        description: Registry namespace or organization
        schema:
          type: string
      - name: module
        in: path
        required: true
        description: Module name
        schema:
          type: string
      - name: n
        in: query
        description: Maximum number of tags to return
        schema:
          type: integer
      - name: last
        in: query
        description: Last tag for pagination
        schema:
          type: string
      responses:
        '200':
          description: List of module tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/{registry}/{module}/manifests/{reference}:
    get:
      operationId: getModuleManifest
      summary: Get Module Manifest
      description: Retrieve the OCI manifest for a specific Timoni module version. The manifest contains the module metadata, CUE definitions, and layer digests.
      tags:
      - Modules
      parameters:
      - name: registry
        in: path
        required: true
        schema:
          type: string
      - name: module
        in: path
        required: true
        schema:
          type: string
      - name: reference
        in: path
        required: true
        description: Tag (e.g., v1.0.0) or digest (sha256:...)
        schema:
          type: string
      responses:
        '200':
          description: OCI manifest for the module
          content:
            application/vnd.oci.image.manifest.v1+json:
              schema:
                $ref: '#/components/schemas/OciManifest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Module or artifact not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    OciManifest:
      type: object
      properties:
        schemaVersion:
          type: integer
        mediaType:
          type: string
        config:
          type: object
          properties:
            mediaType:
              type: string
            size:
              type: integer
            digest:
              type: string
        layers:
          type: array
          items:
            type: object
            properties:
              mediaType:
                type: string
              size:
                type: integer
              digest:
                type: string
              annotations:
                type: object
        annotations:
          type: object
          properties:
            org.opencontainers.image.created:
              type: string
            org.opencontainers.image.source:
              type: string
            org.opencontainers.image.version:
              type: string
            org.opencontainers.image.revision:
              type: string
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              detail:
                type: string
    TagList:
      type: object
      properties:
        name:
          type: string
          description: Repository name
        tags:
          type: array
          items:
            type: string
          description: List of available version tags
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OCI registry authentication token
    basicAuth:
      type: http
      scheme: basic
      description: Username and password authentication for OCI registry