Cayra Deployments API

openapi: 3.2.0
info:
  title: Cayra License Server Deployments API
  description: '# Cayra Chat Agent - License Management Server


    Centralized license management for on-premise deployments.


    ## Features


    - 🔑 License key generation (installation, update, trial)

    - ⏰ Dynamic expiry management (extend/shorten licenses)

    - 🔄 Activation tracking and monitoring

    - 💓 Heartbeat mechanism (1-hour intervals)

    - 📊 Audit logging for compliance

    - 🔐 JWT tokens with RSA-4096 encryption


    ## API Categories


    ### Admin Endpoints (Requires API Key)

    Manage licenses, view activations, update expiry dates.


    ### Client Endpoints (Public)

    Activate licenses, send heartbeats, check status.


    ## Authentication


    Admin endpoints require API key in header:

    ```

    X-Admin-API-Key: your-admin-key-here

    ```


    ## Security


    - 🔒 RSA-4096 asymmetric encryption

    - 🔐 JWT tokens for offline validation

    - 📝 Complete audit trail

    - 🛡️ Rate limiting (Phase 6)'
  contact:
    name: Cayra AI Team
    email: support@cayra.ai
  license:
    name: Proprietary
  version: 1.0.0
tags:
- name: Deployments
paths:
  /v1/deployments:
    get:
      tags:
      - Deployments
      summary: List Deployments
      description: 'List all deployments with optional filtering.


        **Requires**: Admin API key


        **Filters**:

        - company_id: Show only deployments for specific company

        - status: active, terminated, failed

        - environment: production, staging, development'
      operationId: list_deployments_v1_deployments_get
      parameters:
      - name: company_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by company ID
          title: Company Id
        description: Filter by company ID
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/DeploymentStatusEnum'
          - type: 'null'
          description: Filter by status
          title: Status
        description: Filter by status
      - name: environment
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by environment
          title: Environment
        description: Filter by environment
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Max results per page
          default: 50
          title: Limit
        description: Max results per page
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Results offset
          default: 0
          title: Offset
        description: Results offset
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deployments/{deployment_id}:
    get:
      tags:
      - Deployments
      summary: Get Deployment
      description: 'Get detailed information about a specific deployment.


        **Requires**: Admin API key'
      operationId: get_deployment_v1_deployments__deployment_id__get
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Deployment Id
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentDetails'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Deployments
      summary: Terminate Deployment
      description: 'Terminate a deployment.


        **Requires**: Admin API key


        **Note**: This marks the deployment as terminated in the database.

        The actual EC2 instance termination should be performed separately

        via AWS console or CLI.'
      operationId: terminate_deployment_v1_deployments__deployment_id__delete
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Deployment Id
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateDeploymentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminateDeploymentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deployments/{deployment_id}/audit-logs:
    get:
      tags:
      - Deployments
      summary: Get Deployment Audit Logs
      description: 'Get audit logs for a deployment.


        **Requires**: Admin API key'
      operationId: get_deployment_audit_logs_v1_deployments__deployment_id__audit_logs_get
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Deployment Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Max results
          default: 100
          title: Limit
        description: Max results
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Results offset
          default: 0
          title: Offset
        description: Results offset
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentAuditLogResponse'
                title: Response Get Deployment Audit Logs V1 Deployments  Deployment Id  Audit Logs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DeploymentSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        company_id:
          type: string
          format: uuid
          title: Company Id
        subdomain:
          type: string
          title: Subdomain
        status:
          $ref: '#/components/schemas/DeploymentStatusEnum'
        provider:
          $ref: '#/components/schemas/CloudProviderEnum'
        public_url:
          type: string
          title: Public Url
        license_key:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
          description: License key for accessing the deployment
        public_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Ip
        instance_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Type
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        environment:
          anyOf:
          - $ref: '#/components/schemas/DeploymentEnvironmentEnum'
          - type: 'null'
        health_status:
          anyOf:
          - $ref: '#/components/schemas/DeploymentHealthStatusEnum'
          - type: 'null'
        deployed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deployed At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - company_id
      - subdomain
      - status
      - provider
      - public_url
      - public_ip
      - instance_type
      - region
      - environment
      - health_status
      - deployed_at
      - created_at
      title: DeploymentSummary
      description: Lightweight deployment summary for list views
    DeploymentHealthStatusEnum:
      type: string
      enum:
      - healthy
      - unhealthy
      - unknown
      title: DeploymentHealthStatusEnum
      description: Deployment health status enumeration
    DeploymentEnvironmentEnum:
      type: string
      enum:
      - production
      - staging
      - development
      title: DeploymentEnvironmentEnum
      description: Deployment environment type
    TerminateDeploymentRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
          description: Reason for termination
      type: object
      title: TerminateDeploymentRequest
      description: Request to terminate a deployment
    DeploymentDetails:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        company_id:
          type: string
          format: uuid
          title: Company Id
        license_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: License Id
        license_key:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
          description: License key for accessing the deployment (e.g., CAYRA-INST-xxx)
        provisioning_job_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Provisioning Job Id
        subdomain:
          type: string
          title: Subdomain
        status:
          $ref: '#/components/schemas/DeploymentStatusEnum'
        provider:
          $ref: '#/components/schemas/CloudProviderEnum'
        provider_resource_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Resource Id
        provider_metadata:
          type: object
          title: Provider Metadata
        instance_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Id
        public_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Ip
        private_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: Private Ip
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        instance_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Type
        volume_size_gb:
          anyOf:
          - type: integer
          - type: 'null'
          title: Volume Size Gb
        database_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Database Mode
        database_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Database Type
        database_host:
          anyOf:
          - type: string
          - type: 'null'
          title: Database Host
        public_url:
          type: string
          title: Public Url
        installer_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Installer Version
        product_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Version
        environment:
          anyOf:
          - $ref: '#/components/schemas/DeploymentEnvironmentEnum'
          - type: 'null'
        tags:
          type: object
          title: Tags
        health_status:
          anyOf:
          - $ref: '#/components/schemas/DeploymentHealthStatusEnum'
          - type: 'null'
        last_health_check:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Health Check
        created_at:
          type: string
          format: date-time
          title: Created At
        deployed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deployed At
        terminated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Terminated At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - company_id
      - license_id
      - provisioning_job_id
      - subdomain
      - status
      - provider
      - provider_resource_id
      - instance_id
      - public_ip
      - private_ip
      - region
      - instance_type
      - volume_size_gb
      - database_mode
      - database_type
      - database_host
      - public_url
      - installer_version
      - product_version
      - environment
      - health_status
      - last_health_check
      - created_at
      - deployed_at
      - terminated_at
      - updated_at
      title: DeploymentDetails
      description: Full deployment details
    CloudProviderEnum:
      type: string
      enum:
      - aws
      - azure
      title: CloudProviderEnum
    DeploymentStatusEnum:
      type: string
      enum:
      - active
      - terminated
      - failed
      title: DeploymentStatusEnum
      description: Deployment status enumeration
    TerminateDeploymentResponse:
      properties:
        success:
          type: boolean
          title: Success
        deployment_id:
          type: string
          format: uuid
          title: Deployment Id
        provider_action:
          anyOf:
          - type: object
          - type: 'null'
          title: Provider Action
        message:
          type: string
          title: Message
      type: object
      required:
      - success
      - deployment_id
      - message
      title: TerminateDeploymentResponse
      description: Response after terminating deployment
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DeploymentAuditLogResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        deployment_id:
          type: string
          format: uuid
          title: Deployment Id
        action:
          type: string
          title: Action
        performed_by:
          type: string
          title: Performed By
        ip_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Ip Address
        changes:
          type: object
          title: Changes
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - deployment_id
      - action
      - performed_by
      - ip_address
      - changes
      - message
      - created_at
      title: DeploymentAuditLogResponse
      description: Deployment audit log entry
    DeploymentListResponse:
      properties:
        deployments:
          items:
            $ref: '#/components/schemas/DeploymentSummary'
          type: array
          title: Deployments
        total:
          type: integer
          title: Total
        active_count:
          type: integer
          title: Active Count
        max_allowed:
          type: integer
          title: Max Allowed
      type: object
      required:
      - deployments
      - total
      - active_count
      - max_allowed
      title: DeploymentListResponse
      description: Paginated deployment list response