openapi: 3.0.3
info:
  title: Containr API
  description: |
    Self-hosted PaaS on Proxmox - Railway-like platform for container orchestration and deployment.
    
    ## Overview
    Containr provides a comprehensive platform for deploying, managing, and scaling containerized applications on Proxmox infrastructure. This API allows you to manage projects, services, deployments, databases, and more through a RESTful interface.
    
    ## Authentication
    The API uses JWT-based authentication. Include your JWT token in the Authorization header:
    ```
    Authorization: Bearer <your-jwt-token>
    ```
    
    ## Base URL
    ```
    https://your-containr-domain.com/api/v1
    ```
  version: 1.0.0
  contact:
    name: Containr Documentation
    url: https://github.com/your-org/containr
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Development server
  - url: https://your-containr-domain.com/api/v1
    description: Production server

paths:
  # Health Check
  /health:
    get:
      tags:
        - Health
      summary: Health check endpoint
      description: Returns the current status of the API service
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  # Authentication
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticate user and return JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/register:
    post:
      tags:
        - Authentication
      summary: User registration
      description: Register a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: Registration successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # User Management
  /user/profile:
    get:
      tags:
        - User
      summary: Get user profile
      description: Retrieve current user's profile information
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - User
      summary: Update user profile
      description: Update current user's profile information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # Projects
  /projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: Retrieve all projects accessible to the current user
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
        - name: search
          in: query
          description: Search term to filter projects
          schema:
            type: string
      responses:
        '200':
          description: Projects retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'

    post:
      tags:
        - Projects
      summary: Create project
      description: Create a new project
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /projects/{id}:
    get:
      tags:
        - Projects
      summary: Get project
      description: Retrieve a specific project by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Projects
      summary: Update project
      description: Update a specific project
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Projects
      summary: Delete project
      description: Delete a specific project
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
      responses:
        '204':
          description: Project deleted successfully
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # Services
  /projects/{project_id}/services:
    get:
      tags:
        - Services
      summary: List project services
      description: Retrieve all services in a project
      security:
        - bearerAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
      responses:
        '200':
          description: Services retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'

    post:
      tags:
        - Services
      summary: Create service
      description: Create a new service in a project
      security:
        - bearerAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceRequest'
      responses:
        '201':
          description: Service created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'

  /services/{id}:
    get:
      tags:
        - Services
      summary: Get service
      description: Retrieve a specific service
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
      responses:
        '200':
          description: Service retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'

    put:
      tags:
        - Services
      summary: Update service
      description: Update a specific service
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceRequest'
      responses:
        '200':
          description: Service updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'

    delete:
      tags:
        - Services
      summary: Delete service
      description: Delete a specific service
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
      responses:
        '204':
          description: Service deleted successfully

  /services/{id}/deployments:
    get:
      tags:
        - Deployments
      summary: List deployments
      description: Retrieve recent deployments for a specific service
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
      responses:
        '200':
          description: Deployments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentListResponse'

    post:
      tags:
        - Deployments
      summary: Create deployment
      description: Trigger a new deployment for a service
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
      responses:
        '201':
          description: Deployment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'

  /deployments/{id}:
    get:
      tags:
        - Deployments
      summary: Get deployment
      description: Retrieve a deployment with build/runtime details
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Deployment ID
          schema:
            type: string
      responses:
        '200':
          description: Deployment retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  deployment:
                    $ref: '#/components/schemas/Deployment'

  /deployments/{id}/rollback:
    post:
      tags:
        - Deployments
      summary: Rollback deployment
      description: Create a rollback deployment from a previous deployment
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Deployment ID
          schema:
            type: string
      responses:
        '201':
          description: Rollback initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RollbackDeploymentResponse'

  /services/{id}/logs:
    get:
      tags:
        - Logs
      summary: Get service logs
      description: Retrieve service container logs
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Service ID
          schema:
            type: string
        - name: follow
          in: query
          required: false
          description: Stream logs continuously over SSE
          schema:
            type: boolean
            default: false
        - name: tail
          in: query
          required: false
          description: Number of recent log lines to fetch
          schema:
            type: string
            default: '100'
      responses:
        '200':
          description: Service logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceLogsResponse'

  /deployments/{id}/logs:
    get:
      tags:
        - Logs
      summary: Get deployment logs
      description: Retrieve build/runtime logs for a deployment
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Deployment ID
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Select log stream
          schema:
            type: string
            enum: [all, build, runtime]
            default: all
      responses:
        '200':
          description: Deployment logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentLogsResponse'

  # Builds
  /builds:
    get:
      tags:
        - Builds
      summary: List builds
      description: Retrieve builds with optional filtering and pagination
      security:
        - bearerAuth: []
      parameters:
        - name: project_id
          in: query
          description: Filter by project ID
          schema:
            type: string
        - name: service_id
          in: query
          description: Filter by service ID
          schema:
            type: string
        - name: status
          in: query
          description: Filter by build status
          schema:
            type: string
            enum: [pending, running, success, failed, cancelled]
        - name: page
          in: query
          description: 1-based page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of items per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Builds retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildListResponse'

    post:
      tags:
        - Builds
      summary: Start build
      description: Start a new build
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartBuildRequest'
      responses:
        '201':
          description: Build started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartBuildResponse'

  /builds/{id}:
    get:
      tags:
        - Builds
      summary: Get build status
      description: Retrieve build status and details
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Build ID
          schema:
            type: string
      responses:
        '200':
          description: Build status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildStatus'

  /builds/{id}/cancel:
    post:
      tags:
        - Builds
      summary: Cancel build
      description: Cancel an in-progress build
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Build ID
          schema:
            type: string
      responses:
        '200':
          description: Build cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildCancelResponse'

  /builds/{id}/logs:
    get:
      tags:
        - Builds
      summary: Get build logs
      description: Retrieve build logs
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Build ID
          schema:
            type: string
        - name: follow
          in: query
          required: false
          description: Follow logs in realtime (currently returns same text output)
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Build logs retrieved successfully
          content:
            text/plain:
              schema:
                type: string

  # Templates
  /templates:
    get:
      tags:
        - Templates
      summary: List templates
      description: Retrieve service templates with optional category filter
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: query
          required: false
          description: Filter templates by category
          schema:
            type: string
      responses:
        '200':
          description: Templates retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceTemplate'

  /templates/{id}:
    get:
      tags:
        - Templates
      summary: Get template
      description: Retrieve a specific template with parsed config and variables
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateDetailResponse'

  /templates/{id}/deploy:
    post:
      tags:
        - Templates
      summary: Create resource from template
      description: |
        Create a new resource in a project using a selected template.
        For `database` templates, this creates a managed database service.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployTemplateRequest'
      responses:
        '201':
          description: Service created from template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployTemplateResponse'

  # Audit Logs
  /audit-logs:
    get:
      tags:
        - Audit
      summary: List audit logs
      description: Retrieve recent audit log entries for the current user with optional filters
      security:
        - bearerAuth: []
      parameters:
        - name: resource
          in: query
          required: false
          description: Filter audit logs by resource type
          schema:
            type: string
        - name: action
          in: query
          required: false
          description: Filter audit logs by action type
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: 1-based page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          description: Number of entries per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: Audit logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogListResponse'

  /audit-logs/{resource}/{id}:
    get:
      tags:
        - Audit
      summary: List resource audit logs
      description: Retrieve audit log entries for a specific resource and resource ID
      security:
        - bearerAuth: []
      parameters:
        - name: resource
          in: path
          required: true
          description: Resource type
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: Resource ID
          schema:
            type: string
      responses:
        '200':
          description: Resource audit logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogListResponse'

  # Databases
  /databases:
    get:
      tags:
        - Databases
      summary: List databases
      description: Retrieve all managed databases for the authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Databases retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseListResponse'

    post:
      tags:
        - Databases
      summary: Create database
      description: Create a new managed database and start provisioning
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
      responses:
        '201':
          description: Database provisioning started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseCreateResponse'

  /databases/{id}:
    get:
      tags:
        - Databases
      summary: Get database
      description: Retrieve a specific database
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      responses:
        '200':
          description: Database retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
    put:
      tags:
        - Databases
      summary: Update database
      description: Update mutable database metadata (name or plan)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatabaseRequest'
      responses:
        '200':
          description: Database updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      tags:
        - Databases
      summary: Delete database
      description: Delete managed database and associated runtime
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      responses:
        '200':
          description: Database deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /databases/{id}/action:
    post:
      tags:
        - Databases
      summary: Execute database action
      description: Execute start, stop, or restart action for a managed database
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseActionRequest'
      responses:
        '200':
          description: Action accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseActionResponse'

  /databases/{id}/backup:
    post:
      tags:
        - Databases
      summary: Create backup
      description: Create a managed snapshot backup for a database
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      responses:
        '201':
          description: Backup started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseBackupCreateResponse'

  /databases/{id}/restore:
    post:
      tags:
        - Databases
      summary: Restore backup
      description: Restore a managed database from a completed backup
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Database ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseRestoreRequest'
      responses:
        '200':
          description: Restore started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  # Git Integration
  /git/providers:
    get:
      tags:
        - Git
      summary: List Git providers
      description: Retrieve available Git providers
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Git providers retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GitProvider'

    post:
      tags:
        - Git
      summary: Add Git provider
      description: Add a new Git provider
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGitProviderRequest'
      responses:
        '201':
          description: Git provider added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitProvider'

  /git/providers/{providerId}/repositories:
    get:
      tags:
        - Git
      summary: List repositories
      description: Retrieve repositories from a Git provider
      security:
        - bearerAuth: []
      parameters:
        - name: providerId
          in: path
          required: true
          description: Git provider ID
          schema:
            type: string
      responses:
        '200':
          description: Repositories retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GitRepository'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
        details:
          type: object
          description: Additional error details

    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: containr-api
        version:
          type: string
          example: 1.0.0

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: User email address
        password:
          type: string
          format: password
          description: User password

    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token
        user:
          $ref: '#/components/schemas/User'

    RegisterRequest:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          description: User email address
        password:
          type: string
          format: password
          description: User password
        name:
          type: string
          description: User display name

    User:
      type: object
      properties:
        id:
          type: string
          description: User ID
        email:
          type: string
          format: email
          description: User email
        name:
          type: string
          description: User display name
        avatar_url:
          type: string
          description: Optional avatar image URL
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    UpdateUserRequest:
      type: object
      properties:
        name:
          type: string
          description: User display name
        email:
          type: string
          format: email
          description: User email address
        avatar_url:
          type: string
          description: Optional avatar image URL

    Project:
      type: object
      properties:
        id:
          type: string
          description: Project ID
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description
        owner_id:
          type: string
          description: Project owner ID
        created_at:
          type: string
          format: date-time
          description: Project creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        services_count:
          type: integer
          description: Number of services in the project

    CreateProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description

    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description

    ProjectsResponse:
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages

    Service:
      type: object
      properties:
        id:
          type: string
          description: Service ID
        project_id:
          type: string
          description: Project ID
        name:
          type: string
          description: Service name
        type:
          type: string
          enum: [web, worker, database, cron]
          description: Service type
        status:
          type: string
          enum: [running, stopped, building, failed]
          description: Service status
        source:
          $ref: '#/components/schemas/ServiceSource'
        build_config:
          $ref: '#/components/schemas/BuildConfig'
        resources:
          $ref: '#/components/schemas/ResourceConfig'
        created_at:
          type: string
          format: date-time
          description: Service creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    CreateServiceRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Service name
        type:
          type: string
          enum: [web, worker, database, cron]
          description: Service type
        source:
          $ref: '#/components/schemas/ServiceSource'
        build_config:
          $ref: '#/components/schemas/BuildConfig'
        resources:
          $ref: '#/components/schemas/ResourceConfig'

    UpdateServiceRequest:
      type: object
      properties:
        name:
          type: string
          description: Service name
        build_config:
          $ref: '#/components/schemas/BuildConfig'
        resources:
          $ref: '#/components/schemas/ResourceConfig'

    ServiceSource:
      type: object
      properties:
        type:
          type: string
          enum: [git, dockerfile, image]
          description: Source type
        repository:
          type: string
          description: Git repository URL
        branch:
          type: string
          description: Git branch
        root_directory:
          type: string
          description: Root directory for build
        dockerfile:
          type: string
          description: Dockerfile path
        image:
          type: string
          description: Docker image name

    BuildConfig:
      type: object
      properties:
        builder_type:
          type: string
          enum: [nixpacks, dockerfile, image]
          description: Build system type
        build_command:
          type: string
          description: Custom build command
        start_command:
          type: string
          description: Custom start command
        environment_variables:
          type: object
          additionalProperties:
            type: string
          description: Build environment variables

    ResourceConfig:
      type: object
      properties:
        cpu:
          type: string
          description: CPU allocation
        memory:
          type: string
          description: Memory allocation
        storage:
          type: string
          description: Storage allocation

    Deployment:
      type: object
      properties:
        id:
          type: string
          description: Deployment ID
        service_id:
          type: string
          description: Service ID
        commit_hash:
          type: string
          description: Source commit hash
        status:
          type: string
          description: Deployment status
        image_name:
          type: string
          description: Deployed image name
        image_tag:
          type: string
          description: Deployed image tag
        build_log:
          type: string
          description: Build log content
        runtime_log:
          type: string
          description: Runtime log content
        error:
          type: string
          description: Deployment error
        started_at:
          type: string
          format: date-time
          description: Deployment start timestamp
        completed_at:
          type: string
          format: date-time
          description: Deployment completion timestamp
        created_at:
          type: string
          format: date-time
          description: Deployment creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Deployment update timestamp

    DeploymentListResponse:
      type: object
      properties:
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'

    CreateDeploymentRequest:
      type: object
      properties:
        commit_hash:
          type: string
          description: Source commit hash
        branch:
          type: string
          description: Source branch
        trigger:
          type: string
          description: Trigger source (manual, restart, webhook)
        env_vars:
          type: object
          additionalProperties:
            type: string
          description: Runtime environment variable overrides

    RollbackDeploymentResponse:
      type: object
      properties:
        deployment:
          $ref: '#/components/schemas/Deployment'
        message:
          type: string
          description: Rollback result message

    ServiceLogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Log timestamp
        message:
          type: string
          description: Log message
        stream:
          type: string
          description: Log stream identifier

    ServiceLogsResponse:
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLogEntry'
        message:
          type: string
          description: Additional context when logs are unavailable

    DeploymentLogsResponse:
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLogEntry'
        build_log:
          type: string
          description: Build log text
        runtime_log:
          type: string
          description: Runtime log text

    BuildStatus:
      type: object
      properties:
        id:
          type: string
          description: Build ID
        project_id:
          type: string
          description: Project ID
        service_id:
          type: string
          description: Service ID
        status:
          type: string
          enum: [pending, running, success, failed, cancelled]
          description: Build status
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Build progress percentage
        started_at:
          type: string
          format: date-time
          description: Build start time
        completed_at:
          type: string
          format: date-time
          description: Build completion time
        image_name:
          type: string
          description: Target image name
        image_tag:
          type: string
          description: Target image tag
        size:
          type: integer
          format: int64
          description: Built image size in bytes
        error:
          type: string
          description: Build error message
        log:
          type: string
          description: Build logs
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional build metadata

    StartBuildRequest:
      type: object
      required:
        - image_name
        - image_tag
      properties:
        build_type:
          type: string
          description: Build system type; if omitted backend auto-detects
          enum: [railpack, nixpacks, dockerfile, prebuilt]
        source_path:
          type: string
          description: Local source path for build context
        prebuilt_image:
          type: string
          description: Existing image reference when using prebuilt mode
        image_name:
          type: string
          description: Output image name
        image_tag:
          type: string
          description: Output image tag
        registry_url:
          type: string
          description: Optional registry URL for push target
        build_command:
          type: string
          description: Optional build command override
        start_command:
          type: string
          description: Optional runtime command override
        environment:
          type: object
          additionalProperties:
            type: string
          description: Build environment variables
        build_args:
          type: object
          additionalProperties:
            type: string
          description: Build-time arguments
        labels:
          type: object
          additionalProperties:
            type: string
          description: Image labels
        project_id:
          type: string
          description: Associated project ID
        service_id:
          type: string
          description: Associated service ID
        branch:
          type: string
          description: Git branch
        commit:
          type: string
          description: Git commit SHA

    StartBuildResponse:
      type: object
      properties:
        id:
          type: string
          description: Build ID
        status:
          type: string
          enum: [pending, running, success, failed, cancelled]
          description: Initial build status
        image_name:
          type: string
          description: Requested image name
        image_tag:
          type: string
          description: Requested image tag
        size:
          type: integer
          format: int64
          description: Result image size in bytes when available
        digest:
          type: string
          description: Result image digest when available
        build_time:
          type: string
          format: date-time
          description: Build request timestamp
        success:
          type: boolean
          description: Whether request acceptance succeeded
        error:
          type: string
          description: Error details when acceptance failed

    BuildListResponse:
      type: object
      properties:
        builds:
          type: array
          items:
            $ref: '#/components/schemas/BuildStatus'
        total:
          type: integer
          description: Total matching builds
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Page size

    BuildCancelResponse:
      type: object
      properties:
        message:
          type: string
          description: Cancellation result message

    ServiceTemplate:
      type: object
      properties:
        id:
          type: string
          description: Template ID
        name:
          type: string
          description: Template display name
        description:
          type: string
          description: Template description
        category:
          type: string
          description: Template category
        logo:
          type: string
          description: Template logo URL
        config:
          type: string
          description: Raw template config JSON string
        variables:
          type: string
          description: Raw template variables JSON string
        is_official:
          type: boolean
          description: Whether template is an official preset
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    TemplateConfig:
      type: object
      properties:
        type:
          type: string
          description: Service type for created service
        runtime:
          type: string
          description: Runtime or base image
        build_command:
          type: string
          description: Build command
        start_command:
          type: string
          description: Start command
        port:
          type: integer
          description: Service port
        health_check:
          type: string
          description: Health check path
        environment:
          type: object
          additionalProperties:
            type: string
          description: Default environment variables
        dockerfile:
          type: string
          description: Optional dockerfile path
        nixpacks_config:
          type: object
          additionalProperties:
            type: string
          description: Optional nixpacks-specific config

    TemplateVariable:
      type: object
      properties:
        key:
          type: string
          description: Variable key
        label:
          type: string
          description: Display label
        default:
          type: string
          description: Default value
        required:
          type: boolean
          description: Whether variable is required
        secret:
          type: boolean
          description: Whether variable is sensitive
        description:
          type: string
          description: Variable description

    TemplateDetailResponse:
      type: object
      properties:
        template:
          $ref: '#/components/schemas/ServiceTemplate'
        config:
          $ref: '#/components/schemas/TemplateConfig'
        variables:
          type: array
          items:
            $ref: '#/components/schemas/TemplateVariable'

    DeployTemplateRequest:
      type: object
      required:
        - project_id
        - name
      properties:
        project_id:
          type: string
          description: Target project ID
        name:
          type: string
          description: Name for the created service
        plan:
          type: string
          enum: [hobby, starter, standard, business]
          description: Optional managed database plan for database templates
        region:
          type: string
          description: Optional managed database region for database templates
        variables:
          type: object
          additionalProperties:
            type: string
          description: Variable overrides for template deployment

    DeployTemplateResponse:
      type: object
      properties:
        resource:
          type: string
          enum: [service, database]
          description: Type of resource created by template deployment
        service_id:
          type: string
          description: Newly created service ID (set for non-database templates)
        database_id:
          type: string
          description: Newly created managed database ID (set for database templates)
        message:
          type: string
          description: Deployment result message

    AuditLog:
      type: object
      properties:
        id:
          type: string
          description: Audit log ID
        user_id:
          type: string
          description: User ID that triggered action
        user_email:
          type: string
          description: User email snapshot
        resource:
          type: string
          description: Resource type
        resource_id:
          type: string
          description: Resource ID
        action:
          type: string
          description: Action type
        details:
          type: string
          description: JSON-encoded action details
        ip_address:
          type: string
          description: Source IP address
        user_agent:
          type: string
          description: Source user agent
        created_at:
          type: string
          format: date-time
          description: Timestamp when the audit log entry was created

    AuditLogListResponse:
      type: object
      properties:
        audit_logs:
          type: array
          items:
            $ref: '#/components/schemas/AuditLog'

    Database:
      type: object
      properties:
        id:
          type: string
          description: Database ID
        name:
          type: string
          description: Database name
        type:
          type: string
          enum: [postgresql, redis, mysql, mariadb, mongodb, clickhouse, dragonfly]
          description: Database type
        status:
          type: string
          enum: [running, stopped, building, error]
          description: Database status
        connection_url:
          type: string
          description: Database connection URL
        version:
          type: string
          description: Database version
        plan:
          type: string
          enum: [hobby, starter, standard, business]
          description: Provisioning plan
        region:
          type: string
          description: Provisioning region
        metrics:
          $ref: '#/components/schemas/DatabaseMetrics'
        backups:
          $ref: '#/components/schemas/DatabaseBackupConfig'
        settings:
          $ref: '#/components/schemas/DatabaseSettings'
        created_at:
          type: string
          format: date-time
          description: Database creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    CreateDatabaseRequest:
      type: object
      required:
        - name
        - type
        - plan
        - region
      properties:
        name:
          type: string
          description: Database name
        type:
          type: string
          enum: [postgresql, redis, mysql, mariadb, mongodb, clickhouse, dragonfly]
          description: Database type
        plan:
          type: string
          enum: [hobby, starter, standard, business]
          description: Database plan
        region:
          type: string
          description: Database region

    UpdateDatabaseRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated database name
        plan:
          type: string
          enum: [hobby, starter, standard, business]
          description: Updated database plan

    DatabaseActionRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [start, stop, restart]
          description: Action to execute

    DatabaseRestoreRequest:
      type: object
      required:
        - backup_id
      properties:
        backup_id:
          type: string
          description: Backup identifier to restore

    DatabaseCreateResponse:
      type: object
      properties:
        id:
          type: string
          description: Database ID
        message:
          type: string
        status:
          type: string
          enum: [building]

    DatabaseActionResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          enum: [running, stopped, building, error]

    DatabaseBackupCreateResponse:
      type: object
      properties:
        backup_id:
          type: string
        message:
          type: string
        status:
          type: string
          enum: [in_progress]

    DatabaseListResponse:
      type: object
      properties:
        databases:
          type: array
          items:
            $ref: '#/components/schemas/Database'

    DatabaseMetrics:
      type: object
      properties:
        cpu:
          type: number
        memory:
          type: number
        storage:
          type: number
        connections:
          type: integer
        read_iops:
          type: integer
        write_iops:
          type: integer
        network_in:
          type: number
        network_out:
          type: number

    DatabaseBackup:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        size:
          type: string
        status:
          type: string
          enum: [completed, failed, in_progress]

    DatabaseBackupConfig:
      type: object
      properties:
        enabled:
          type: boolean
        last_backup:
          type: string
          format: date-time
        retention:
          type: integer
        next_backup:
          type: string
          format: date-time
        backups:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseBackup'

    DatabaseSettings:
      type: object
      properties:
        max_connections:
          type: integer
        timeout:
          type: integer
        ssl:
          type: boolean
        logging:
          type: boolean

    MessageResponse:
      type: object
      properties:
        message:
          type: string

    GitProvider:
      type: object
      properties:
        id:
          type: string
          description: Provider ID
        type:
          type: string
          enum: [github, gitlab, bitbucket]
          description: Provider type
        name:
          type: string
          description: Provider display name
        access_token:
          type: string
          description: Encrypted access token
        created_at:
          type: string
          format: date-time
          description: Provider creation timestamp

    CreateGitProviderRequest:
      type: object
      required:
        - type
        - access_token
      properties:
        type:
          type: string
          enum: [github, gitlab, bitbucket]
          description: Provider type
        name:
          type: string
          description: Provider display name
        access_token:
          type: string
          description: Access token

    GitRepository:
      type: object
      properties:
        id:
          type: string
          description: Repository ID
        name:
          type: string
          description: Repository name
        full_name:
          type: string
          description: Repository full name
        description:
          type: string
          description: Repository description
        private:
          type: boolean
          description: Whether repository is private
        default_branch:
          type: string
          description: Default branch
        clone_url:
          type: string
          description: Clone URL
        web_url:
          type: string
          description: Web URL

tags:
  - name: Health
    description: Health check endpoints
  - name: Authentication
    description: User authentication and authorization
  - name: User
    description: User profile management
  - name: Projects
    description: Project management
  - name: Services
    description: Service management
  - name: Deployments
    description: Deployment lifecycle management
  - name: Logs
    description: Service and deployment log retrieval
  - name: Builds
    description: Build management
  - name: Templates
    description: Service template catalog and deployment
  - name: Audit
    description: Audit event history and resource-level trails
  - name: Databases
    description: Database management
  - name: Git
    description: Git integration