openapi: 3.2.0
info:
  title: Karada Deployments API
  version: 1.0.0
  description: Spec-Driven API definition for Karada MCP Platform
servers:
- url: https://api.karada.ai
  description: Production API
- url: http://localhost:8080
  description: Local development API
tags:
- name: Deployments
paths:
  /api/v1/deployments/list:
    get:
      summary: List deployments for a project or team
      operationId: listDeployments
      tags:
      - Deployments
      security:
      - BearerAuth: []
      parameters:
      - name: team_id
        in: query
        required: false
        description: Team UUID to list deployments for
        schema:
          type: string
          format: uuid
      - name: project_id
        in: query
        required: false
        description: Project UUID to list deployments for
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of deployments
  /api/v1/deployments/deploy:
    post:
      summary: Trigger deployment
      operationId: createDeployment
      tags:
      - Deployments
      security:
      - BearerAuth: []
      responses:
        '202':
          description: Deployment initiated
  /api/v1/deployments/{id}/logs:
    get:
      summary: Get deployment logs
      operationId: getDeploymentLogs
      tags:
      - Deployments
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deployment logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: string
                    example: '[INFO] Deployment initialized

                      [INFO] Starting build...'
  /api/v1/deployments/{id}/logs/stream:
    get:
      summary: Stream deployment logs in real-time
      description: Streams deployment logs in real-time using Server-Sent Events (SSE). Closes stream when deployment reaches terminal status.
      operationId: streamDeploymentLogs
      tags:
      - Deployments
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Realtime log event stream (text/event-stream)
          content:
            text/event-stream:
              schema:
                type: string
  /api/v1/deployments/{id}:
    get:
      summary: Get deployment status and details
      operationId: getDeployment
      tags:
      - Deployments
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deployment details
    delete:
      summary: Cancel or delete deployment
      operationId: deleteDeployment
      tags:
      - Deployments
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deployment canceled
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT