openapi: 3.0.3
info:
  title: SearchStax Provisioning Authentication Deployments API
  description: The SearchStax Provisioning API is a REST interface for creating and managing Solr deployments in the SearchStax Managed Search cloud. It supports deployment lifecycle management including creation, deletion, restart, backup and restore, node management, authentication configuration, webhook management, and usage reporting.
  version: 2.0.0
  contact:
    url: https://www.searchstax.com/docs/searchstax-cloud-apis-overview/
servers:
- url: https://app.searchstax.com/api/rest/v2
  description: SearchStax Provisioning API v2
security:
- tokenAuth: []
tags:
- name: Deployments
paths:
  /account/{account_name}/deployment/:
    get:
      operationId: listDeployments
      summary: List Deployments
      description: Retrieve all Solr deployments for the specified account with pagination.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        schema:
          type: integer
          default: 25
      responses:
        '200':
          description: List of deployments
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    nullable: true
                  previous:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized
    post:
      operationId: createDeployment
      summary: Create Deployment
      description: Create a new Solr deployment. Provisioning may take up to an hour to complete. Only Account Owner, Admin, or Technical Contact roles may invoke this endpoint.
      tags:
      - Deployments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
      responses:
        '201':
          description: Deployment creation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
  /account/{account_name}/deployment/{uid}/:
    get:
      operationId: getDeployment
      summary: Get Deployment
      description: Retrieve comprehensive details about a specific Solr deployment.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/deploymentUid'
      responses:
        '200':
          description: Deployment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '404':
          description: Deployment not found
    delete:
      operationId: deleteDeployment
      summary: Delete Deployment
      description: Delete a deployment. Subject to termination lock restrictions. Optionally retain scheduled backups after deletion.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/deploymentUid'
      - name: retain_backups
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: Deployment deleted
        '403':
          description: Termination lock active
        '404':
          description: Deployment not found
  /account/{account_name}/deployment/{uid}/deployment-health/:
    get:
      operationId: getDeploymentHealth
      summary: Get Deployment Health
      description: Returns the health status of the deployment as OK, Warn, or Error.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/deploymentUid'
      responses:
        '200':
          description: Deployment health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Warn
                    - Error
  /account/{account_name}/deployment/{uid}/collection-health/:
    get:
      operationId: getCollectionHealth
      summary: Get Collection Health
      description: Checks whether all Solr collections are healthy or degraded.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/deploymentUid'
      responses:
        '200':
          description: Collection health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  healthy:
                    type: boolean
                  collections:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        status:
                          type: string
  /account/{account_name}/deployment/{uid}/rolling-restart/:
    put:
      operationId: rollingRestart
      summary: Rolling Restart
      description: Sequentially restart cluster nodes without downtime. Can restart Solr nodes, ZooKeeper nodes, or both.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/deploymentUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - solr
              - zookeeper
              properties:
                solr:
                  type: boolean
                  description: Restart Solr nodes
                zookeeper:
                  type: boolean
                  description: Restart ZooKeeper nodes
      responses:
        '200':
          description: Restart initiated
        '400':
          description: Invalid request
components:
  schemas:
    CreateDeploymentRequest:
      type: object
      required:
      - name
      - application
      - application_version
      - termination_lock
      - plan_type
      - plan
      - region_id
      - cloud_provider_id
      properties:
        name:
          type: string
          description: Deployment name
        application:
          type: string
          enum:
          - Solr
        application_version:
          type: string
          description: Solr version (e.g., "9.4.1")
        termination_lock:
          type: boolean
          description: Shield deployment from accidental deletion
        plan_type:
          type: string
          enum:
          - DedicatedDeployment
        plan:
          type: string
          description: Plan identifier (e.g., "NDN2-AWS-S")
        region_id:
          type: string
          description: Cloud region identifier (e.g., "us-east-1")
        cloud_provider_id:
          type: string
          enum:
          - aws
          - azure
          - gcp
        num_additional_app_nodes:
          type: integer
          description: Additional Solr application nodes
        private_vpc:
          type: integer
          description: Private VPC ID for network isolation
    Deployment:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
          - provisioning
          - running
          - stopped
          - error
        application:
          type: string
        application_version:
          type: string
        plan:
          type: string
        cloud_provider_id:
          type: string
        region_id:
          type: string
        termination_lock:
          type: boolean
        solr_url:
          type: string
        created:
          type: string
          format: date-time
  parameters:
    accountName:
      name: account_name
      in: path
      required: true
      description: SearchStax account name
      schema:
        type: string
    deploymentUid:
      name: uid
      in: path
      required: true
      description: Deployment unique identifier
      schema:
        type: string
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      description: Token obtained from /obtain-auth-token/ endpoint