openapi: 3.1.0
info:
  title: Couchbase Analytics Service REST API
  description: >-
    The Couchbase Analytics Service REST API provides access to the Analytics
    service for running complex analytical queries on operational data without
    impacting performance of key-value operations. It supports SQL++ queries
    for analytics, management of links to external data sources, and
    configuration of user-defined libraries. The service enables real-time
    analytics on JSON data alongside transactional workloads.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
  description: Couchbase Analytics Service REST API Documentation
  url: https://docs.couchbase.com/server/current/analytics/rest-analytics.html
servers:
  - url: https://localhost:8095
    description: Analytics Service (default port)
  - url: https://localhost:18095
    description: Analytics Service (SSL)
tags:
  - name: Analytics Admin
    description: >-
      Endpoints for administering and monitoring the Analytics service.
  - name: Analytics Configuration
    description: >-
      Endpoints for configuring Analytics nodes and clusters.
  - name: Analytics Library
    description: >-
      Endpoints for managing JavaScript libraries used for user-defined functions.
  - name: Analytics Query
    description: >-
      Endpoints for executing SQL++ analytics queries and retrieving results.
  - name: Analytics Settings
    description: >-
      Endpoints for configuring Analytics service settings.
security:
  - basicAuth: []
paths:
  /analytics/service:
    post:
      operationId: executeAnalyticsQuery
      summary: Execute an analytics query
      description: >-
        Executes a SQL++ analytics query against the Analytics service. The
        endpoint implements the same HTTP interface as the Couchbase Query
        service but targets the Analytics engine for complex analytical workloads.
      tags:
        - Analytics Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryResult'
        '400':
          description: Invalid query syntax or parameters
        '401':
          description: Unauthorized access
  /analytics/node/agg/stats/remaining:
    get:
      operationId: getAnalyticsRemainingMutations
      summary: Get remaining mutations to be synced
      description: >-
        Returns the number of mutations that have not yet been synced to the
        Analytics service from the Data service. Useful for monitoring data
        ingestion progress.
      tags:
        - Analytics Admin
      responses:
        '200':
          description: Successful retrieval of remaining mutation counts
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                  description: Remaining mutations per dataset
        '401':
          description: Unauthorized access
  /analytics/status/ingestion:
    get:
      operationId: getAnalyticsIngestionStatus
      summary: Get analytics data ingestion status
      description: >-
        Returns the current status of data ingestion from Couchbase Server
        into the Analytics service, including details about each dataset
        and its synchronization state.
      tags:
        - Analytics Admin
      responses:
        '200':
          description: Successful retrieval of ingestion status
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized access
  /analytics/cluster:
    get:
      operationId: getAnalyticsClusterStatus
      summary: Get analytics cluster status
      description: >-
        Returns the status of the Analytics cluster including information
        about all Analytics nodes and their states.
      tags:
        - Analytics Admin
      responses:
        '200':
          description: Successful retrieval of cluster status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsClusterStatus'
        '401':
          description: Unauthorized access
  /analytics/cluster/restart:
    post:
      operationId: restartAnalyticsCluster
      summary: Restart analytics cluster
      description: >-
        Restarts the Analytics service across all nodes in the cluster.
      tags:
        - Analytics Admin
      responses:
        '202':
          description: Restart initiated successfully
        '401':
          description: Unauthorized access
  /analytics/config/service:
    get:
      operationId: getAnalyticsServiceConfig
      summary: Get analytics service configuration
      description: >-
        Returns the current configuration of the Analytics service.
      tags:
        - Analytics Configuration
      responses:
        '200':
          description: Successful retrieval of service configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsServiceConfig'
        '401':
          description: Unauthorized access
    put:
      operationId: updateAnalyticsServiceConfig
      summary: Update analytics service configuration
      description: >-
        Updates the configuration settings for the Analytics service.
      tags:
        - Analytics Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsServiceConfig'
      responses:
        '200':
          description: Configuration updated successfully
        '400':
          description: Invalid configuration
        '401':
          description: Unauthorized access
  /analytics/config/node:
    get:
      operationId: getAnalyticsNodeConfig
      summary: Get analytics node configuration
      description: >-
        Returns the configuration of the current Analytics node.
      tags:
        - Analytics Configuration
      responses:
        '200':
          description: Successful retrieval of node configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsNodeConfig'
        '401':
          description: Unauthorized access
    put:
      operationId: updateAnalyticsNodeConfig
      summary: Update analytics node configuration
      description: >-
        Updates the configuration settings for the current Analytics node.
      tags:
        - Analytics Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsNodeConfig'
      responses:
        '200':
          description: Node configuration updated successfully
        '400':
          description: Invalid configuration
        '401':
          description: Unauthorized access
  /settings/analytics:
    get:
      operationId: getAnalyticsSettings
      summary: Get analytics settings
      description: >-
        Returns the current cluster-level Analytics service settings.
      tags:
        - Analytics Settings
      responses:
        '200':
          description: Successful retrieval of analytics settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSettings'
        '401':
          description: Unauthorized access
    post:
      operationId: updateAnalyticsSettings
      summary: Update analytics settings
      description: >-
        Updates the cluster-level Analytics service settings.
      tags:
        - Analytics Settings
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AnalyticsSettings'
      responses:
        '200':
          description: Analytics settings updated successfully
        '400':
          description: Invalid settings
        '401':
          description: Unauthorized access
  /analytics/library/{scope}/{name}:
    put:
      operationId: createOrUpdateLibrary
      summary: Create or update a library
      description: >-
        Creates or updates a JavaScript library that can be used to define
        SQL++ user-defined functions in the Analytics service.
      tags:
        - Analytics Library
      parameters:
        - name: scope
          in: path
          required: true
          description: The scope of the library
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The name of the library
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: The JavaScript library code
      responses:
        '200':
          description: Library created or updated successfully
        '400':
          description: Invalid library code
        '401':
          description: Unauthorized access
    delete:
      operationId: deleteLibrary
      summary: Delete a library
      description: >-
        Deletes a JavaScript library from the Analytics service.
      tags:
        - Analytics Library
      parameters:
        - name: scope
          in: path
          required: true
          description: The scope of the library
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The name of the library
          schema:
            type: string
      responses:
        '200':
          description: Library deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Library not found
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using Couchbase Server credentials.
  schemas:
    AnalyticsQueryRequest:
      type: object
      description: Analytics query execution request
      required:
        - statement
      properties:
        statement:
          type: string
          description: The SQL++ analytics statement to execute
        pretty:
          type: boolean
          description: Whether to format the results with indentation
        readonly:
          type: boolean
          description: Whether to restrict to read-only operations
        client_context_id:
          type: string
          description: Client-provided context identifier for request tracking
        timeout:
          type: string
          description: Maximum execution time for the query (e.g., 10s, 5m)
        scan_consistency:
          type: string
          description: Consistency requirement for the query
          enum:
            - not_bounded
            - request_plus
        args:
          type: array
          description: Positional parameters for the query
          items: {}
    AnalyticsQueryResult:
      type: object
      description: Analytics query execution result
      properties:
        requestID:
          type: string
          description: Unique identifier for the request
        clientContextID:
          type: string
          description: Client-provided context identifier
        signature:
          type: object
          description: Schema signature of the results
        results:
          type: array
          description: Array of result documents
          items: {}
        status:
          type: string
          description: Query execution status
          enum:
            - success
            - running
            - errors
            - completed
            - stopped
            - timeout
            - fatal
        metrics:
          type: object
          description: Query execution metrics
          properties:
            elapsedTime:
              type: string
              description: Total elapsed time
            executionTime:
              type: string
              description: Execution time
            resultCount:
              type: integer
              description: Number of results returned
            resultSize:
              type: integer
              description: Size of results in bytes
            processedObjects:
              type: integer
              description: Number of objects processed
            errorCount:
              type: integer
              description: Number of errors encountered
            warningCount:
              type: integer
              description: Number of warnings generated
        errors:
          type: array
          description: List of errors if any occurred
          items:
            type: object
            properties:
              code:
                type: integer
                description: Error code
              msg:
                type: string
                description: Error message
    AnalyticsClusterStatus:
      type: object
      description: Analytics cluster status information
      properties:
        state:
          type: string
          description: Overall state of the Analytics cluster
          enum:
            - ACTIVE
            - UNUSABLE
            - RECOVERING
        nodes:
          type: array
          description: List of Analytics nodes and their states
          items:
            type: object
            properties:
              nodeId:
                type: string
                description: Node identifier
              state:
                type: string
                description: State of the individual node
              partitions:
                type: array
                description: Data partitions on the node
                items:
                  type: object
    AnalyticsServiceConfig:
      type: object
      description: Analytics service configuration
      properties:
        activeMemoryGlobalBudget:
          type: integer
          description: Global memory budget in bytes
        activeStopTimeout:
          type: integer
          description: Timeout for stopping active operations in seconds
        activeSuspendTimeout:
          type: integer
          description: Timeout for suspending active operations in seconds
        analyticsBroadcastDcpStateMutationCount:
          type: integer
          description: DCP state mutation broadcast count
        compilerFrameLimit:
          type: integer
          description: Maximum number of frames in a query plan
        compilerGroupmemory:
          type: integer
          description: Memory allocated for groupby operations in bytes
        compilerJoinmemory:
          type: integer
          description: Memory allocated for join operations in bytes
        compilerSortmemory:
          type: integer
          description: Memory allocated for sort operations in bytes
        logLevel:
          type: string
          description: Log level for the Analytics service
          enum:
            - DEBUG
            - TRACE
            - INFO
            - WARN
            - ERROR
            - FATAL
    AnalyticsNodeConfig:
      type: object
      description: Analytics node-level configuration
      properties:
        storageBuffercachePagesize:
          type: integer
          description: Buffer cache page size in bytes
        storageBuffercacheSize:
          type: integer
          description: Buffer cache size in bytes
        storageMemorycomponentNumcomponents:
          type: integer
          description: Number of memory components
    AnalyticsSettings:
      type: object
      description: Cluster-level analytics settings
      properties:
        numReplicas:
          type: integer
          description: Number of Analytics replicas
          minimum: 0
          maximum: 3