openapi: 3.0.0
info:
  title: Sandbox
  description: |
    Sandbox APIs for Zoho Books.

    These APIs help administrators manage **Sandbox environments** that are used to safely test configuration and feature changes before pushing them to the production organization. Sandboxes are also commonly used to test integrations/extensions in an isolated setup (see: [Test Extensions in Sandbox](https://www.zoho.com/books/developer/extensions/test-extensions.html)).

    ### Early access
    Sandbox is an early-access capability. Availability and behavior can vary by account/edition. Build automations (including MCP tools) should handle “not enabled / not available” responses gracefully.

    ### Concepts
    - **Sandbox as a test org copy**: A sandbox can be created as a copy of your original (production) Books organization. You can perform actions/configuration changes in the sandbox similarly to how you would in the production org, but in an isolated test environment.
    - **Production org vs Sandbox org**: Some endpoints act on sandbox configuration in the *production organization* context (create/update sandbox, list changes available to push, push changes). Other endpoints act inside the *sandbox organization* context (list changes inside sandbox, mark reviewed/unreviewed).
    - **Component changes**: A “change” represents a configuration/component modification that can be reviewed and optionally deployed to production.
    - **Review workflow**: Changes can be marked as reviewed/unreviewed to control readiness for deployment.

    ### Recommended MCP / AI workflows
    - **Discover sandboxes**: `GET /sandboxes`
    - **Inspect one sandbox**: `GET /sandboxes/{sandbox_id}`
    - **See what would be deployed**: `GET /sandboxes/{sandbox_id}/changes`
    - **Validate before deployment**: `POST /sandboxes/{sandbox_id}/changes/validatepush`
    - **Deploy to production**: `POST /sandboxes/{sandbox_id}/changes/push`
    - **Audit history**: `GET /sandboxes/logs`
    - **Inside sandbox org (triage/review)**:
      - `GET /sandboxes/changes`
      - `PUT /sandboxes/changes/markasreviewed` / `markasunreviewed`

    ### Notes for callers
    - These endpoints are **admin-only** and use `ZohoBooks.settings.*` scopes.
    - Treat IDs (`sandbox_id`, `change_ids`, `component_ids`) as opaque strings.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: sandbox
    description: Sandbox Module
paths:
  /sandboxes:
    get:
      tags:
        - sandbox
      operationId: list_sandboxes
      summary: List all sandboxes
      description: |
        Get all sandbox configurations available for the production organization.

        Use this as the first step to obtain `sandbox_id` values for subsequent operations (view details, list changes, validate/push, rebuild, etc.).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandboxes-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - sandbox
      operationId: create_sandbox
      summary: Create a sandbox
      description: |
        Create a new sandbox in the production organization.

        Typical usage:
        - Create a sandbox for safe testing (configuration changes, integrations, extensions).
        - After creation, use `GET /sandboxes/{sandbox_id}` to verify status and `GET /sandboxes/{sandbox_id}/changes` once changes accumulate.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-create-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandbox-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
  /sandboxes/{sandbox_id}:
    get:
      tags:
        - sandbox
      operationId: get_sandbox
      summary: Get a sandbox
      description: |
        Get configuration details of a particular sandbox.

        Use this to:
        - Confirm sandbox metadata (name/description/active status).
        - Validate that a `sandbox_id` from listing is still valid.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandbox-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - sandbox
      operationId: update_sandbox
      summary: Update a sandbox
      description: |
        Edit sandbox configurations (e.g., name/description).

        Use `GET /sandboxes/editpage` if you need UI-oriented edit context (such as share targets) before updating.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-create-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandbox-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - sandbox
      operationId: delete_sandbox
      summary: Delete a sandbox
      description: |
        Delete the sandbox from the production organization.

        Notes:
        - Use `force_delete=true` only if you intend to delete the sandbox regardless of its current state.
        - Deleting a sandbox is destructive; consider auditing with `GET /sandboxes/logs` beforehand.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
        - name: force_delete
          in: query
          required: false
          description: Force delete the sandbox.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
  /sandboxes/editpage:
    get:
      tags:
        - sandbox
      operationId: get_sandbox_edit_page
      summary: Get sandbox edit page details
      description: |
        Fetch edit-page context for a sandbox (production org context).

        Use this when building administrative tooling (or MCP actions) that needs:
        - Sandbox details used by edit UI
        - Sharing/visibility information (see `shared_to` in response)
      parameters:
        - name: sandbox_id
          in: query
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandbox-edit-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
  /sandboxes/{sandbox_id}/changes:
    get:
      tags:
        - sandbox
      operationId: list_sandbox_changes_production
      summary: List changes in production org
      description: |
        Get all available component changes from the sandbox in the **production organization** context.

        This is the primary “what will be deployed?” API.

        Typical flow:
        - Call this to gather candidate `change_ids`.
        - Optionally validate with `POST /sandboxes/{sandbox_id}/changes/validatepush`.
        - Deploy with `POST /sandboxes/{sandbox_id}/changes/push`.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changes-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
  /sandboxes/{sandbox_id}/changes/validatepush:
    post:
      tags:
        - sandbox
      operationId: validate_push_changes
      summary: Validate push to production
      description: |
        Validate that the selected sandbox changes can be pushed to the production organization.

        Provide `change_ids` in the request body. Use the response to detect blockers/conflicts before attempting the actual push.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-sync-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/change-details-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
  /sandboxes/{sandbox_id}/changes/push:
    post:
      tags:
        - sandbox
      operationId: push_changes_to_production
      summary: Push changes to production
      description: |
        Deploy sandbox component changes to the production organization.

        Recommended flow:
        - Gather `change_ids` from `GET /sandboxes/{sandbox_id}/changes`
        - Validate using `POST /sandboxes/{sandbox_id}/changes/validatepush`
        - Push here with the same `change_ids`
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-sync-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changes-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
  /sandboxes/{sandbox_id}/status:
    put:
      tags:
        - sandbox
      operationId: update_sandbox_status
      summary: Activate or deactivate sandbox
      description: |
        Activate or deactivate a sandbox.

        Use this to temporarily disable sandbox usage without deleting it.
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
        - name: active
          in: query
          required: true
          description: Set to true to activate, false to deactivate.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
  /sandboxes/{sandbox_id}/rebuild:
    put:
      tags:
        - sandbox
      operationId: rebuild_sandbox
      summary: Rebuild sandbox
      description: |
        Rebuild the sandbox.

        Use this when the sandbox needs to be refreshed/recreated from production state (exact behavior may vary by rollout and org settings).
      parameters:
        - name: sandbox_id
          in: path
          required: true
          description: Unique identifier of the sandbox.
          schema:
            type: string
          example: '460000000026001'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sandbox-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
  /sandboxes/logs:
    get:
      tags:
        - sandbox
      operationId: list_sandbox_deployment_logs
      summary: List deployment logs
      description: |
        Fetch sandbox deployment logs (audit trail) from the production organization context.

        Use this to:
        - Audit pushes/sync operations
        - Trace who deployed what and when (optionally filter by `sandbox_id` / `user_id`)
        - Build “recent activity” views for admins and MCP tools
      parameters:
        - name: page
          in: query
          required: false
          description: Page number.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: Number of records per page.
          schema:
            type: integer
            default: 10
        - name: filter_by
          in: query
          required: false
          description: Filter for deployment logs.
          schema:
            type: string
        - name: from_date
          in: query
          required: false
          description: From date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: to_date
          in: query
          required: false
          description: To date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: sandbox_id
          in: query
          required: false
          description: Sandbox ID to filter logs.
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          description: User ID to filter logs.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deployment-logs-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
  /sandboxes/changes:
    get:
      tags:
        - sandbox
      operationId: list_sandbox_changes_sandbox_org
      summary: List changes in sandbox org
      description: |
        Get all changes within the **sandbox organization** context.

        Use this when operating inside sandbox to triage what changed:
        - `change_type` is required (`new_changes` or `tested_changes`).
        - Optionally filter by `status` (e.g., already deployed vs pending).
      parameters:
        - name: change_type
          in: query
          required: true
          description: Type of changes (e.g. new_changes, tested_changes).
          schema:
            type: string
            enum:
              - new_changes
              - tested_changes
        - name: status
          in: query
          required: false
          description: Filter by deployment status (e.g. deployed, yet_to_be_deployed).
          schema:
            type: string
            enum:
              - deployed
              - yet_to_be_deployed
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changes-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
  /sandboxes/changes/markasreviewed:
    put:
      tags:
        - sandbox
      operationId: mark_changes_as_reviewed
      summary: Mark changes as reviewed
      description: |
        Mark sandbox components/changes as reviewed (ready to deploy) in the sandbox org context.

        Provide `change_ids` and/or `component_ids` depending on what you are marking.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-sync-request'
      responses:
        '200':
          description: OK
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
  /sandboxes/changes/markasunreviewed:
    put:
      tags:
        - sandbox
      operationId: mark_changes_as_unreviewed
      summary: Mark changes as unreviewed
      description: |
        Mark sandbox components/changes as unreviewed in the sandbox org context.

        Use this to revert “ready to deploy” status for the selected items.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandbox-sync-request'
      responses:
        '200':
          description: OK
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
components:
  parameters: {}
  schemas:
    sandbox-create-request:
      type: object
      description: |
        Request body for creating or updating a sandbox.

        Note: The full set of accepted fields may expand over time as Sandbox evolves (early access). Clients should ignore unknown fields returned by the API.
      properties:
        name:
          type: string
          description: Name of the sandbox.
        description:
          type: string
          description: Description of the sandbox.
    sandbox-sync-request:
      type: object
      description: |
        Request body for sync-related operations:
        - Validate push (`/changes/validatepush`)
        - Push to production (`/changes/push`)
        - Mark reviewed/unreviewed (`/changes/markasreviewed`, `/changes/markasunreviewed`)

        Use `change_ids` when operating on whole changesets and `component_ids` when operating on specific components inside a change (as supported).
      properties:
        change_ids:
          type: array
          description: List of change IDs (from the changes listing APIs).
          items:
            type: string
        component_ids:
          type: array
          description: List of component IDs (primarily for mark as reviewed/unreviewed).
          items:
            type: string
    sandboxes-response:
      type: object
      properties:
        sandboxes:
          type: array
          description: List of sandbox configurations.
          items:
            $ref: '#/components/schemas/sandbox-details'
    sandbox-response:
      type: object
      properties:
        sandbox:
          $ref: '#/components/schemas/sandbox-details'
    sandbox-edit-response:
      type: object
      description: Edit page details for a sandbox (includes share targets in `shared_to` when applicable).
      properties:
        sandbox:
          $ref: '#/components/schemas/sandbox-details'
        shared_to:
          type: array
          description: Users/groups the sandbox is shared with.
    sandbox-details:
      type: object
      description: Sandbox configuration details (production org context).
      properties:
        sandbox_id:
          type: string
          description: Unique identifier of the sandbox.
        name:
          type: string
          description: Sandbox name.
        description:
          type: string
          description: Sandbox description.
        active:
          type: boolean
          description: Indicates whether the sandbox is active.
    changes-response:
      type: object
      properties:
        changes:
          type: array
          description: List of component changes.
    change-details-response:
      type: object
      properties:
        change_details:
          type: object
          description: Validation result for push.
    deployment-logs-response:
      type: object
      properties:
        deployment_logs:
          type: array
          description: List of deployment log entries.
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoBooks.settings.READ: Read Settings
            ZohoBooks.settings.CREATE: Create Settings
            ZohoBooks.settings.UPDATE: Update Settings
            ZohoBooks.settings.DELETE: Delete Settings
