api.yaml

openapi: 3.0.3
info:
  title: Kploy API
  description: |
    API for the Kploy GitOps Kubernetes deployment system.

    Two audiences share this surface. The kploy operator runs in each
    cluster and authenticates with a cluster-scoped bearer token. The
    kploy CLI is used by humans and authenticates with a GitHub OAuth
    user-to-server token. Operations are tagged with `operator` or
    `user` to make it clear which security scheme applies; the
    document-level default applies to both.
  version: 1.0.0
servers:
  - url: /api/v1
    description: API base path
tags:
  - name: operator
    description: Operator-facing endpoints (cluster bearer token).
  - name: user
    description: User-facing endpoints used by the `kploy` CLI (GitHub OAuth user token).
security:
  - ClusterToken: []
  - UserToken: []
paths:

  ###################################################################
  # User-facing endpoints (CLI)
  ###################################################################

  /auth/device-flow-config:
    get:
      tags: [user]
      security: []
      summary: GitHub OAuth Device Flow config for this kploy instance
      description: |
        Returns the GitHub App client ID the CLI should use for Device Flow
        login. Unauthenticated by design — this lets `kploy auth login`
        bootstrap before the user has a token.
      operationId: getDeviceFlowConfig
      responses:
        '200':
          description: Device flow config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceFlowConfig'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List organizations
      description: Returns the GitHub organizations where the Kploy GitHub App is installed and the caller has access.
      operationId: listOrgs
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List repositories
      description: Returns the repositories in the org for which Kploy has at least one environment configured.
      operationId: listRepos
      parameters:
        - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: List of repositories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repository'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/envs:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List environments
      operationId: listEnvs
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
      responses:
        '200':
          description: List of environments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Environment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [user]
      security:
        - UserToken: []
      summary: Create an environment
      operationId: createEnv
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentCreate'
      responses:
        '201':
          description: Environment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Environment name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/envs/{env}:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: Get environment
      operationId: getEnv
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      responses:
        '200':
          description: Environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/deployments/{deployment_id}/logs:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List the log lines for a deployment
      description: |
        Returns the deployment's log output as a JSON array, ordered by
        emission timestamp. Suitable for batch viewing; no streaming yet.
      operationId: listDeploymentLogs
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/DeploymentID'
      responses:
        '200':
          description: List of log entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentLogEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/clusters:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List clusters in the org
      operationId: listClusters
      parameters:
        - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: List of clusters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [user]
      security:
        - UserToken: []
      summary: Create a cluster
      description: |
        Mints a new cluster with a one-shot bearer token. The token is
        returned plaintext exactly once.
      operationId: createCluster
      parameters:
        - $ref: '#/components/parameters/Org'
      responses:
        '201':
          description: Cluster created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  ###################################################################
  # Operator-facing endpoints
  ###################################################################

  /cluster/{cluster_id}:
    get:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Get cluster information
      description: Returns the cluster's environments. Path parameter is redundant with the auth token but kept for compatibility with existing operators.
      operationId: getCluster
      parameters:
        - name: cluster_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cluster information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/envs/{env}/manifest:
    get:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Get the latest manifest for an environment
      operationId: getEnvironmentManifest
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
        - name: If-None-Match
          in: header
          schema:
            type: string
          description: ETag-like value (the X-Kploy-Manifest-SHA returned previously). Server returns 304 if unchanged.
      responses:
        '200':
          description: Environment manifest
          headers:
            X-Kploy-Manifest-SHA:
              schema:
                type: string
              description: SHA of the manifest
            X-Kploy-Head-SHA:
              schema:
                type: string
              description: SHA of the environment's branch HEAD
          content:
            application/x-yaml:
              schema:
                type: string
        '204':
          description: No manifest has been built for this environment yet
        '304':
          description: Not modified
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/envs/{env}/tracked-images:
    get:
      tags: [operator, user]
      summary: List tracked images
      description: |
        Operators use this to know which images to poll for new tags.
        Users use it to inspect what's currently being tracked. Same
        response for both — auth scheme is the only difference.
      operationId: listTrackedImages
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      responses:
        '200':
          description: List of tracked images
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrackedImage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Update available tags for one tracked image
      description: |
        Operator reports the set of tags discovered for a single image
        in its registry. May trigger auto-deployment.
      operationId: updateTrackedImage
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                available_tags:
                  type: array
                  items:
                    type: string
              required: [name, available_tags]
      responses:
        '200':
          description: Updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags: [user]
      security:
        - UserToken: []
      summary: Replace the tracked-image list for an environment
      description: |
        Adds new images (`available_tags` starts empty), preserves
        existing images that remain in the list, removes any that
        aren't listed.
      operationId: replaceTrackedImages
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
              required: [images]
      responses:
        '200':
          description: Updated tracked-image list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrackedImage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Invalid image name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/envs/{env}/deployments:
    get:
      tags: [user]
      security:
        - UserToken: []
      summary: List recent deployments for an environment
      operationId: listDeployments
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      responses:
        '200':
          description: List of deployments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Deployment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Trigger a deployment
      description: |
        Operator-side trigger: invoked after the operator detects a new
        manifest SHA on the env's branch. Performs the GitHub
        required-status-checks dance and creates a GitHub Deployment.
      operationId: createDeployment
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/Env'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sha:
                  type: string
              required: [sha]
      responses:
        '200':
          description: Deployment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Deployment already in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentSummary'
        '422':
          description: GitHub rejected the deployment because required status checks failed
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Required status checks are still running; retry later

  /orgs/{org}/repos/{repo}/deployments/{deployment_id}/progress:
    post:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Update deployment progress
      description: Operator streams output lines as the deployment runs.
      operationId: updateDeploymentProgress
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/DeploymentID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                output:
                  type: string
                  nullable: true
                timestamp:
                  type: string
                  format: date-time
                  nullable: true
      responses:
        '200':
          description: Progress recorded
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /orgs/{org}/repos/{repo}/deployments/{deployment_id}/complete:
    patch:
      tags: [operator]
      security:
        - ClusterToken: []
      summary: Mark deployment complete
      operationId: completeDeployment
      parameters:
        - $ref: '#/components/parameters/Org'
        - $ref: '#/components/parameters/Repo'
        - $ref: '#/components/parameters/DeploymentID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/DeploymentStatus'
              required: [status]
      responses:
        '200':
          description: Marked complete
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    ClusterToken:
      type: apiKey
      in: header
      name: X-Kploy-Token
      description: Cluster bearer token. Used by the kploy operator.
    UserToken:
      type: http
      scheme: bearer
      description: GitHub OAuth user-to-server token (issued via GitHub Device Flow). Used by the kploy CLI.

  parameters:
    Org:
      name: org
      in: path
      required: true
      schema:
        type: string
      description: GitHub organization (or user) login.
    Repo:
      name: repo
      in: path
      required: true
      schema:
        type: string
      description: Repository name (no owner prefix).
    Env:
      name: env
      in: path
      required: true
      schema:
        type: string
      description: Environment name.
    DeploymentID:
      name: deployment_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
      description: GitHub deployment ID.

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
      required: [message]

    Organization:
      type: object
      properties:
        name:
          type: string
        avatar_url:
          type: string
      required: [name, avatar_url]

    Repository:
      type: object
      properties:
        name:
          type: string
      required: [name]

    Environment:
      type: object
      properties:
        name:
          type: string
        branch:
          type: string
        cluster_id:
          type: string
        kubernetes_namespace:
          type: string
        head_sha:
          type: string
        manifests_sha:
          type: string
          nullable: true
      required: [name, branch, cluster_id, kubernetes_namespace, head_sha]

    EnvironmentCreate:
      type: object
      properties:
        name:
          type: string
        cluster_id:
          type: string
        branch:
          type: string
        kubernetes_namespace:
          type: string
        tracked_images:
          type: array
          items:
            type: string
      required: [name, cluster_id, branch, kubernetes_namespace]

    EnvironmentSummary:
      type: object
      description: Compact environment representation used by `GET /cluster/{cluster_id}` so the operator can see all its envs at once.
      properties:
        name:
          type: string
        repository_name:
          type: string
        manifests_sha:
          type: string
          nullable: true
        namespace:
          type: string
      required: [name, repository_name, namespace]

    TrackedImage:
      type: object
      properties:
        name:
          type: string
        available_tags:
          type: array
          items:
            type: string
        current_tag:
          type: string
          nullable: true
      required: [name, available_tags]

    Cluster:
      type: object
      properties:
        id:
          type: string
        connected:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
          nullable: true
      required: [id, connected]

    ClusterCreated:
      type: object
      properties:
        id:
          type: string
        token:
          type: string
      required: [id, token]

    DeviceFlowConfig:
      type: object
      properties:
        github_client_id:
          type: string
      required: [github_client_id]

    ClusterDetail:
      type: object
      description: Cluster + its environments. Returned by `GET /cluster/{cluster_id}` for the operator.
      properties:
        id:
          type: string
        organization:
          type: string
        environments:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentSummary'
      required: [id, organization, environments]

    DeploymentStatus:
      type: string
      enum: [success, failure, error]

    Deployment:
      type: object
      properties:
        id:
          type: integer
          format: int64
        environment:
          type: string
        commit_sha:
          type: string
        commit_message:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required: [id, environment, commit_sha, status, created_at, updated_at]

    DeploymentLogEntry:
      type: object
      properties:
        output:
          type: string
        emitted_at:
          type: string
          format: date-time
      required: [output, emitted_at]

    DeploymentSummary:
      type: object
      description: Minimal deployment shape returned to the operator after a `POST .../deployments`.
      properties:
        id:
          type: integer
          format: int64
        environment:
          type: string
          nullable: true
        namespace:
          type: string
          nullable: true
      required: [id]