openapi: 3.1.0
info:
  title: Quub Exchange - Sandbox & Test Harness API
  version: 2.0.0
  license:
    name: Proprietary
    url: https://quub.exchange/license
  description:
    "Provides an isolated test harness for developers and integrators.


    **Features**

    - Create multiple sandbox environments

    - Generate mock data for projects, orders, or accounts

    - Travel through simulated time

    - Reset or delete entire environments safely

    "
servers:
  - url: https://sandbox-api.quub.exchange/v1
    description: Sandbox API (Isolated Environment)
paths:
  /sandbox/envs:
    get:
      operationId: listSandboxEnvironments
      summary: List sandbox environments
      tags:
        - Sandbox
      description: Retrieve all sandbox environments accessible to the authenticated user.
      security:
        - oauth2:
            - read:sandbox
        - apiKey: []
      parameters:
        - $ref: ./common/pagination.yaml#/components/parameters/cursor
        - $ref: ./common/pagination.yaml#/components/parameters/limit
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: List of sandbox environments
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SandboxEnvironment"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
    post:
      operationId: createSandboxEnvironment
      summary: Create sandbox environment
      tags:
        - Sandbox
      description:
        "Create a new isolated sandbox environment for testing purposes.

        Each environment has its own ledger, accounts, and tokens.

        "
      security:
        - oauth2:
            - write:sandbox
        - apiKey: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: My Project Test Env
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "201":
          description: Sandbox environment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxEnvironment"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /sandbox/envs/{envId}:
    parameters:
      - name: envId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getSandboxEnvironment
      summary: Get sandbox environment details
      tags:
        - Sandbox
      description: Retrieve metadata about a specific sandbox environment.
      security:
        - oauth2:
            - read:sandbox
        - apiKey: []
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: Sandbox environment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxEnvironment"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
    delete:
      operationId: deleteSandboxEnvironment
      summary: Delete sandbox environment
      tags:
        - Sandbox
      description: Permanently delete a sandbox environment and all contained test data.
      security:
        - oauth2:
            - admin:sandbox
        - apiKey: []
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "404":
          $ref: ./common/responses.yaml#/components/responses/NotFound
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "204":
          $ref: ./common/responses.yaml#/components/responses/NoContentResponse
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /sandbox/envs/{envId}/generate-data:
    post:
      operationId: generateTestData
      summary: Generate test data
      tags:
        - Test Data
      description: Populate the sandbox environment with mock users, projects, and trades.
      security:
        - oauth2:
            - write:sandbox
        - apiKey: []
      parameters:
        - name: envId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dataTypes:
                  type: array
                  items:
                    type: string
                    enum:
                      - accounts
                      - projects
                      - tokens
                      - orders
                count:
                  type: integer
                  example: 50
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "201":
          description: Mock data generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxEnvironment"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /sandbox/envs/{envId}/time-travel:
    post:
      operationId: setSandboxTime
      summary: Set sandbox time
      tags:
        - Time Travel
      description: Move forward or backward in simulated sandbox time for testing time-dependent logic.
      security:
        - oauth2:
            - write:sandbox
        - apiKey: []
      parameters:
        - name: envId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - timestamp
              properties:
                timestamp:
                  type: string
                  format: date-time
                  example: "2025-11-01T12:00:00Z"
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: Sandbox time updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxEnvironment"
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
  /sandbox/envs/{envId}/reset:
    post:
      operationId: resetSandboxEnvironment
      summary: Reset sandbox environment
      tags:
        - Reset
      description: Reset the sandbox to its initial clean state (clears all generated data).
      security:
        - oauth2:
            - write:sandbox
        - apiKey: []
      parameters:
        - name: envId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "403":
          $ref: ./common/responses.yaml#/components/responses/Forbidden
        "409":
          $ref: ./common/responses.yaml#/components/responses/Conflict
        "422":
          $ref: ./common/responses.yaml#/components/responses/ValidationError
        "429":
          $ref: ./common/responses.yaml#/components/responses/TooManyRequests
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError
        "200":
          description: Sandbox environment reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SandboxEnvironment"
components:
  securitySchemes:
    bearerAuth:
      $ref: ./common/components.yaml#/components/securitySchemes/bearerAuth
    oauth2:
      $ref: ./common/components.yaml#/components/securitySchemes/oauth2
    apiKey:
      $ref: ./common/components.yaml#/components/securitySchemes/apiKey
  schemas:
    SandboxEnvironment:
      type: object
      description: Represents an isolated sandbox environment instance.
      properties:
        id:
          type: string
          format: uuid
          example: 9d2a5a64-7e10-4a7f-b213-7e0bfc6b5e5f
        name:
          type: string
          example: Dev Team Sandbox
        status:
          type: string
          enum:
            - ACTIVE
            - PAUSED
            - RESETTING
            - DELETED
          example: ACTIVE
        currentTime:
          type: string
          format: date-time
          example: "2025-10-21T17:00:00Z"
        createdAt:
          type: string
          format: date-time
          example: "2025-10-01T08:00:00Z"
        updatedAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
          example:
            network: sandbox-chain
            version: v1.0.0
tags:
  - name: Reset
    description: Reset operations
  - name: Sandbox
    description: Sandbox operations
  - name: Test Data
    description: Test Data operations
  - name: Time Travel
    description: Time Travel operations