openapi: 3.1.0
info:
  title: OptScale REST API
  description: >-
    OptScale is an open-source FinOps and cloud cost optimization platform by
    Hystax. The REST API exposes endpoints for managing organizations, cloud
    accounts, employees, pools, resources, expenses, recommendations, and
    optimization runs across AWS, Azure, GCP, Alibaba Cloud, and Kubernetes.
  version: '2.0'
  contact:
    name: Hystax OptScale
    url: https://hystax.com/optscale/
    email: info@hystax.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: OptScale Documentation
  url: https://hystax.com/documentation/optscale/
servers:
  - url: https://{host}/restapi/v2
    description: OptScale REST API server
    variables:
      host:
        default: my.optscale.com
        description: OptScale hostname
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: User authentication and token management
  - name: Organizations
    description: Organization management
  - name: Cloud Accounts
    description: Cloud account connections (AWS, Azure, GCP, Alibaba, Kubernetes)
  - name: Employees
    description: Organization employees and roles
  - name: Pools
    description: Budget pools and limits
  - name: Resources
    description: Cloud resources and assignment rules
  - name: Expenses
    description: Cost reporting and expense breakdowns
  - name: Recommendations
    description: Cost optimization recommendations
  - name: Optimizations
    description: Optimization checklist runs and results
paths:
  /auth/v2/tokens:
    post:
      tags: [Authentication]
      summary: Create an authentication token
      operationId: createToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, format: password }
              required: [email, password]
      responses:
        '201':
          description: Token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
  /organizations:
    get:
      tags: [Organizations]
      summary: List organizations
      operationId: listOrganizations
      responses:
        '200':
          description: A list of organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
    post:
      tags: [Organizations]
      summary: Create an organization
      operationId: createOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '201':
          description: Organization created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
  /organizations/{organization_id}:
    get:
      tags: [Organizations]
      summary: Get an organization
      operationId: getOrganization
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          description: The organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
    delete:
      tags: [Organizations]
      summary: Delete an organization
      operationId: deleteOrganization
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '204':
          description: Organization deleted
  /organizations/{organization_id}/cloud_accounts:
    get:
      tags: [Cloud Accounts]
      summary: List cloud accounts for an organization
      operationId: listCloudAccounts
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          description: Cloud accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CloudAccount'
    post:
      tags: [Cloud Accounts]
      summary: Create a cloud account connection
      operationId: createCloudAccount
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudAccount'
      responses:
        '201':
          description: Cloud account connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAccount'
  /cloud_accounts/{cloud_account_id}:
    get:
      tags: [Cloud Accounts]
      summary: Get cloud account
      operationId: getCloudAccount
      parameters:
        - $ref: '#/components/parameters/CloudAccountId'
      responses:
        '200':
          description: Cloud account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAccount'
    delete:
      tags: [Cloud Accounts]
      summary: Disconnect a cloud account
      operationId: deleteCloudAccount
      parameters:
        - $ref: '#/components/parameters/CloudAccountId'
      responses:
        '204':
          description: Cloud account disconnected
  /organizations/{organization_id}/employees:
    get:
      tags: [Employees]
      summary: List organization employees
      operationId: listEmployees
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          description: Employees list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
  /organizations/{organization_id}/pools:
    get:
      tags: [Pools]
      summary: List pools
      operationId: listPools
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          description: Pool list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pool'
    post:
      tags: [Pools]
      summary: Create a pool
      operationId: createPool
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pool'
      responses:
        '201':
          description: Pool created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pool'
  /pools/{pool_id}:
    get:
      tags: [Pools]
      summary: Get pool
      operationId: getPool
      parameters:
        - name: pool_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Pool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pool'
  /cloud_accounts/{cloud_account_id}/cloud_resources:
    get:
      tags: [Resources]
      summary: List cloud resources for a cloud account
      operationId: listCloudResources
      parameters:
        - $ref: '#/components/parameters/CloudAccountId'
      responses:
        '200':
          description: Resources list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CloudResource'
  /organizations/{organization_id}/expenses:
    get:
      tags: [Expenses]
      summary: Query expenses
      operationId: getExpenses
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
        - name: start_date
          in: query
          schema: { type: integer, description: 'Unix timestamp' }
        - name: end_date
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: Expenses summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpensesSummary'
  /organizations/{organization_id}/optimizations:
    get:
      tags: [Recommendations, Optimizations]
      summary: List optimization recommendations
      operationId: listOptimizations
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          description: Optimization recommendations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Optimization'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    OrganizationId:
      name: organization_id
      in: path
      required: true
      schema: { type: string }
    CloudAccountId:
      name: cloud_account_id
      in: path
      required: true
      schema: { type: string }
  schemas:
    Token:
      type: object
      properties:
        token: { type: string }
        user_id: { type: string }
        valid_until: { type: integer }
    Organization:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        pool_id: { type: string }
        currency: { type: string }
        created_at: { type: integer }
    CloudAccount:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type:
          type: string
          enum: [aws_cnr, azure_cnr, gcp_cnr, alibaba_cnr, kubernetes_cnr]
        config: { type: object, additionalProperties: true }
        organization_id: { type: string }
        last_import_at: { type: integer }
    Employee:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        auth_user_id: { type: string }
        organization_id: { type: string }
    Pool:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        parent_id: { type: string, nullable: true }
        limit: { type: number }
        organization_id: { type: string }
    CloudResource:
      type: object
      properties:
        id: { type: string }
        cloud_resource_id: { type: string }
        resource_type: { type: string }
        region: { type: string }
        cloud_account_id: { type: string }
        active: { type: boolean }
        first_seen: { type: integer }
        last_seen: { type: integer }
    ExpensesSummary:
      type: object
      properties:
        total: { type: number }
        previous_total: { type: number }
        breakdown:
          type: object
          additionalProperties: { type: number }
    Optimization:
      type: object
      properties:
        module: { type: string }
        count: { type: integer }
        saving: { type: number }
        items:
          type: array
          items: { type: object, additionalProperties: true }