openapi: 3.0.0
info:
  title: DOTA API
  version: 1.0.0
  description: API documentation for DOTA backend acquisition, management and authentication endpoints.
servers:
  - url: http://localhost:3000
    description: Local server

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Account:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        email: { type: string }
        createdTime: { type: integer }
    AccessKey:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        friendlyName: { type: string }
        description: { type: string }
        createdBy: { type: string }
        createdTime: { type: integer }
        expires: { type: integer }
        scope: { type: string }
    App:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        displayName: { type: string }
        createdTime: { type: integer }
        tenantId: { type: string }
    Deployment:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        key: { type: string }
        createdTime: { type: integer }
        package: { $ref: '#/components/schemas/Package' }
    Package:
      type: object
      properties:
        label: { type: string }
        appVersion: { type: string }
        description: { type: string }
        uploadTime: { type: integer }
        blobUrl: { type: string }
        size: { type: integer }
        isMandatory: { type: boolean }
        isDisabled: { type: boolean }
    Collaborator:
      type: object
      properties:
        email: { type: string }
        accountId: { type: string }
        permission: { type: string }
    Organization:
      type: object
      properties:
        id: { type: string }
        displayName: { type: string }
        role: { type: string }
    Metrics:
      type: object
      additionalProperties:
        type: object
        properties:
          active: { type: integer }
          downloaded: { type: integer }
          failed: { type: integer }
          installed: { type: integer }
          totalActive: { type: integer }

security:
  - BearerAuth: []

paths:
  /account:
    get:
      summary: Get current user's account
      responses:
        '200':
          description: Account object
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
    post:
      summary: Create a new account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  $ref: '#/components/schemas/Account'
      responses:
        '200':
          description: Account ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    type: string

  /accessKeys:
    get:
      summary: List all access keys for the user
      responses:
        '200':
          description: List of access keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessKeys:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessKey'
    post:
      summary: Create a new access key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                description: { type: string }
                ttl: { type: integer }
      responses:
        '201':
          description: Created access key
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessKey:
                    $ref: '#/components/schemas/AccessKey'

  /apps:
    get:
      summary: List all apps for the user
      responses:
        '200':
          description: List of apps
          content:
            application/json:
              schema:
                type: object
                properties:
                  apps:
                    type: array
                    items:
                      $ref: '#/components/schemas/App'
    post:
      summary: Create a new app
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                displayName: { type: string }
                manuallyProvisionDeployments: { type: boolean }
      responses:
        '201':
          description: Created app
          content:
            application/json:
              schema:
                type: object
                properties:
                  app:
                    $ref: '#/components/schemas/App'

  /apps/{appName}:
    get:
      summary: Get details for a specific app
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: App details
          content:
            application/json:
              schema:
                type: object
                properties:
                  app:
                    $ref: '#/components/schemas/App'
    patch:
      summary: Update app metadata
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
      responses:
        '200':
          description: Updated app
          content:
            application/json:
              schema:
                type: object
                properties:
                  app:
                    $ref: '#/components/schemas/App'
    delete:
      summary: Delete an app
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      responses:
        '201':
          description: App deleted

  /apps/{appName}/collaborators:
    get:
      summary: List collaborators for an app
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: List of collaborators
          content:
            application/json:
              schema:
                type: object
                properties:
                  collaborators:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collaborator'

  /apps/{appName}/collaborators/{email}:
    post:
      summary: Add a collaborator
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: email
          required: true
          schema: { type: string }
      responses:
        '201':
          description: Collaborator added
    patch:
      summary: Update collaborator role
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: email
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role: { type: string }
      responses:
        '204':
          description: Collaborator updated
    delete:
      summary: Remove a collaborator
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: email
          required: true
          schema: { type: string }
      responses:
        '201':
          description: Collaborator removed

  /apps/{appName}/deployments:
    get:
      summary: List deployments for an app
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: List of deployments
          content:
            application/json:
              schema:
                type: object
                properties:
                  deployments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deployment'
    post:
      summary: Create a deployment
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                key: { type: string }
      responses:
        '201':
          description: Deployment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  deployment:
                    $ref: '#/components/schemas/Deployment'

  /apps/{appName}/deployments/{deploymentName}:
    get:
      summary: Get deployment details
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deployment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  deployment:
                    $ref: '#/components/schemas/Deployment'
    patch:
      summary: Update deployment metadata
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Deployment'
      responses:
        '200':
          description: Deployment updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  deployment:
                    $ref: '#/components/schemas/Deployment'
    delete:
      summary: Delete a deployment
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      responses:
        '201':
          description: Deployment deleted

  /apps/{appName}/deployments/{deploymentName}/release:
    post:
      summary: Release a new update
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                package:
                  type: string
                  format: binary
                packageInfo:
                  type: string
      responses:
        '201':
          description: Release created
          content:
            application/json:
              schema:
                type: object
                properties:
                  package:
                    $ref: '#/components/schemas/Package'
    patch:
      summary: Patch latest release metadata
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Package'
      responses:
        '200':
          description: Release updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  package:
                    $ref: '#/components/schemas/Package'

  /apps/{appName}/deployments/{deploymentName}/history:
    get:
      summary: Get release history
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Release history
          content:
            application/json:
              schema:
                type: object
                properties:
                  history:
                    type: array
                    items:
                      $ref: '#/components/schemas/Package'
    delete:
      summary: Clear release history
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      responses:
        '201':
          description: History cleared

  /apps/{appName}/deployments/{deploymentName}/metrics:
    get:
      summary: Get deployment metrics
      parameters:
        - in: path
          name: appName
          required: true
          schema: { type: string }
        - in: path
          name: deploymentName
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deployment metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  metrics:
                    $ref: '#/components/schemas/Metrics'

  /tenants:
    get:
      summary: List organizations/tenants for the user
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: object
                properties:
                  organisations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'