OptScale REST API

naftiko: 1.0.0-alpha2
info:
  label: 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.
  tags:
  - Optscale
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: optscale
    baseUri: https://my.optscale.com/restapi/v2
    description: OptScale REST API HTTP API.
    authentication:
      type: bearer
      token: '{{OPTSCALE_TOKEN}}'
    resources:
    - name: auth-v2-tokens
      path: /auth/v2/tokens
      operations:
      - name: createtoken
        method: POST
        description: Create an authentication token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations
      path: /organizations
      operations:
      - name: listorganizations
        method: GET
        description: List organizations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createorganization
        method: POST
        description: Create an organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id
      path: /organizations/{organization_id}
      operations:
      - name: getorganization
        method: GET
        description: Get an organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteorganization
        method: DELETE
        description: Delete an organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id-cloud-accounts
      path: /organizations/{organization_id}/cloud_accounts
      operations:
      - name: listcloudaccounts
        method: GET
        description: List cloud accounts for an organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcloudaccount
        method: POST
        description: Create a cloud account connection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: cloud-accounts-cloud-account-id
      path: /cloud_accounts/{cloud_account_id}
      operations:
      - name: getcloudaccount
        method: GET
        description: Get cloud account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletecloudaccount
        method: DELETE
        description: Disconnect a cloud account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id-employees
      path: /organizations/{organization_id}/employees
      operations:
      - name: listemployees
        method: GET
        description: List organization employees
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id-pools
      path: /organizations/{organization_id}/pools
      operations:
      - name: listpools
        method: GET
        description: List pools
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createpool
        method: POST
        description: Create a pool
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: pools-pool-id
      path: /pools/{pool_id}
      operations:
      - name: getpool
        method: GET
        description: Get pool
        inputParameters:
        - name: pool_id
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: cloud-accounts-cloud-account-id-cloud-resources
      path: /cloud_accounts/{cloud_account_id}/cloud_resources
      operations:
      - name: listcloudresources
        method: GET
        description: List cloud resources for a cloud account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id-expenses
      path: /organizations/{organization_id}/expenses
      operations:
      - name: getexpenses
        method: GET
        description: Query expenses
        inputParameters:
        - name: start_date
          in: query
          type: integer
        - name: end_date
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organizations-organization-id-optimizations
      path: /organizations/{organization_id}/optimizations
      operations:
      - name: listoptimizations
        method: GET
        description: List optimization recommendations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: optscale-rest
    description: REST adapter for OptScale REST API.
    resources:
    - path: /auth/v2/tokens
      name: createtoken
      operations:
      - method: POST
        name: createtoken
        description: Create an authentication token
        call: optscale.createtoken
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations
      name: listorganizations
      operations:
      - method: GET
        name: listorganizations
        description: List organizations
        call: optscale.listorganizations
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations
      name: createorganization
      operations:
      - method: POST
        name: createorganization
        description: Create an organization
        call: optscale.createorganization
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}
      name: getorganization
      operations:
      - method: GET
        name: getorganization
        description: Get an organization
        call: optscale.getorganization
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}
      name: deleteorganization
      operations:
      - method: DELETE
        name: deleteorganization
        description: Delete an organization
        call: optscale.deleteorganization
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/cloud_accounts
      name: listcloudaccounts
      operations:
      - method: GET
        name: listcloudaccounts
        description: List cloud accounts for an organization
        call: optscale.listcloudaccounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/cloud_accounts
      name: createcloudaccount
      operations:
      - method: POST
        name: createcloudaccount
        description: Create a cloud account connection
        call: optscale.createcloudaccount
        outputParameters:
        - type: object
          mapping: $.
    - path: /cloud_accounts/{cloud_account_id}
      name: getcloudaccount
      operations:
      - method: GET
        name: getcloudaccount
        description: Get cloud account
        call: optscale.getcloudaccount
        outputParameters:
        - type: object
          mapping: $.
    - path: /cloud_accounts/{cloud_account_id}
      name: deletecloudaccount
      operations:
      - method: DELETE
        name: deletecloudaccount
        description: Disconnect a cloud account
        call: optscale.deletecloudaccount
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/employees
      name: listemployees
      operations:
      - method: GET
        name: listemployees
        description: List organization employees
        call: optscale.listemployees
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/pools
      name: listpools
      operations:
      - method: GET
        name: listpools
        description: List pools
        call: optscale.listpools
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/pools
      name: createpool
      operations:
      - method: POST
        name: createpool
        description: Create a pool
        call: optscale.createpool
        outputParameters:
        - type: object
          mapping: $.
    - path: /pools/{pool_id}
      name: getpool
      operations:
      - method: GET
        name: getpool
        description: Get pool
        call: optscale.getpool
        with:
          pool_id: rest.pool_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /cloud_accounts/{cloud_account_id}/cloud_resources
      name: listcloudresources
      operations:
      - method: GET
        name: listcloudresources
        description: List cloud resources for a cloud account
        call: optscale.listcloudresources
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/expenses
      name: getexpenses
      operations:
      - method: GET
        name: getexpenses
        description: Query expenses
        call: optscale.getexpenses
        outputParameters:
        - type: object
          mapping: $.
    - path: /organizations/{organization_id}/optimizations
      name: listoptimizations
      operations:
      - method: GET
        name: listoptimizations
        description: List optimization recommendations
        call: optscale.listoptimizations
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: optscale-mcp
    transport: http
    description: MCP adapter for OptScale REST API for AI agent use.
    tools:
    - name: createtoken
      description: Create an authentication token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: optscale.createtoken
      outputParameters:
      - type: object
        mapping: $.
    - name: listorganizations
      description: List organizations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listorganizations
      outputParameters:
      - type: object
        mapping: $.
    - name: createorganization
      description: Create an organization
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: optscale.createorganization
      outputParameters:
      - type: object
        mapping: $.
    - name: getorganization
      description: Get an organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.getorganization
      outputParameters:
      - type: object
        mapping: $.
    - name: deleteorganization
      description: Delete an organization
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: optscale.deleteorganization
      outputParameters:
      - type: object
        mapping: $.
    - name: listcloudaccounts
      description: List cloud accounts for an organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listcloudaccounts
      outputParameters:
      - type: object
        mapping: $.
    - name: createcloudaccount
      description: Create a cloud account connection
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: optscale.createcloudaccount
      outputParameters:
      - type: object
        mapping: $.
    - name: getcloudaccount
      description: Get cloud account
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.getcloudaccount
      outputParameters:
      - type: object
        mapping: $.
    - name: deletecloudaccount
      description: Disconnect a cloud account
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: optscale.deletecloudaccount
      outputParameters:
      - type: object
        mapping: $.
    - name: listemployees
      description: List organization employees
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listemployees
      outputParameters:
      - type: object
        mapping: $.
    - name: listpools
      description: List pools
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listpools
      outputParameters:
      - type: object
        mapping: $.
    - name: createpool
      description: Create a pool
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: optscale.createpool
      outputParameters:
      - type: object
        mapping: $.
    - name: getpool
      description: Get pool
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.getpool
      with:
        pool_id: tools.pool_id
      inputParameters:
      - name: pool_id
        type: string
        description: pool_id
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listcloudresources
      description: List cloud resources for a cloud account
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listcloudresources
      outputParameters:
      - type: object
        mapping: $.
    - name: getexpenses
      description: Query expenses
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.getexpenses
      with:
        start_date: tools.start_date
        end_date: tools.end_date
      inputParameters:
      - name: start_date
        type: integer
        description: start_date
      - name: end_date
        type: integer
        description: end_date
      outputParameters:
      - type: object
        mapping: $.
    - name: listoptimizations
      description: List optimization recommendations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: optscale.listoptimizations
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    OPTSCALE_TOKEN: OPTSCALE_TOKEN