openapi: 3.1.0
info:
  title: Couchbase Eventing Service REST API
  description: >-
    The Couchbase Eventing Service REST API provides methods for deploying and
    managing Eventing Functions that respond to data changes in real time.
    Eventing Functions allow developers to write server-side JavaScript logic
    triggered by document mutations, timers, or external events. The API
    supports creating, deploying, pausing, and undeploying functions, as well
    as monitoring their execution status and statistics.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
  description: Couchbase Eventing Service REST API Documentation
  url: https://docs.couchbase.com/server/current/eventing/eventing-api.html
servers:
  - url: https://localhost:8096
    description: Eventing Service (default port)
  - url: https://localhost:18096
    description: Eventing Service (SSL)
tags:
  - name: Configuration
    description: >-
      Endpoints for configuring Eventing Service settings.
  - name: Functions
    description: >-
      Endpoints for creating, retrieving, updating, and deleting Eventing
      Functions.
  - name: Import Export
    description: >-
      Endpoints for importing and exporting Eventing Function definitions.
  - name: Lifecycle
    description: >-
      Endpoints for deploying, undeploying, pausing, and resuming Eventing
      Functions.
  - name: Logging
    description: >-
      Endpoints for retrieving Eventing Function application logs.
  - name: Statistics
    description: >-
      Endpoints for monitoring Eventing Function execution statistics and status.
security:
  - basicAuth: []
paths:
  /api/v1/functions:
    get:
      operationId: listEventingFunctions
      summary: List all Eventing Functions
      description: >-
        Returns the definitions of all Eventing Functions including their
        source code, bindings, and deployment settings.
      tags:
        - Functions
      responses:
        '200':
          description: Successful retrieval of function list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventingFunction'
        '401':
          description: Unauthorized access
  /api/v1/functions/{functionName}:
    get:
      operationId: getEventingFunction
      summary: Get an Eventing Function
      description: >-
        Returns the definition of a specific Eventing Function including
        its source code, bindings, and deployment settings.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Successful retrieval of function definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventingFunction'
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
    post:
      operationId: createOrUpdateEventingFunction
      summary: Create or update an Eventing Function
      description: >-
        Creates a new Eventing Function or updates an existing one with the
        provided definition. The function name in the URL must match the
        appname in the request body.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/functionName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventingFunction'
      responses:
        '200':
          description: Function created or updated successfully
        '400':
          description: Invalid function definition
        '401':
          description: Unauthorized access
    delete:
      operationId: deleteEventingFunction
      summary: Delete an Eventing Function
      description: >-
        Deletes the specified Eventing Function. Only functions in undeployed
        state can be deleted.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
        '422':
          description: Function is deployed and cannot be deleted
  /api/v1/functions/{functionName}/deploy:
    post:
      operationId: deployEventingFunction
      summary: Deploy an Eventing Function
      description: >-
        Deploys an undeployed Eventing Function, starting it to process
        document mutations and execute its handler code.
      tags:
        - Lifecycle
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function deployment initiated
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/functions/{functionName}/undeploy:
    post:
      operationId: undeployEventingFunction
      summary: Undeploy an Eventing Function
      description: >-
        Undeploys a deployed Eventing Function, stopping it from processing
        document mutations.
      tags:
        - Lifecycle
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function undeployment initiated
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/functions/{functionName}/pause:
    post:
      operationId: pauseEventingFunction
      summary: Pause an Eventing Function
      description: >-
        Pauses a deployed Eventing Function and creates a DCP checkpoint
        so that on a subsequent resume no mutations will be lost.
      tags:
        - Lifecycle
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function paused successfully
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/functions/{functionName}/resume:
    post:
      operationId: resumeEventingFunction
      summary: Resume an Eventing Function
      description: >-
        Resumes a paused Eventing Function from its DCP checkpoint,
        continuing to process mutations from where it left off.
      tags:
        - Lifecycle
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function resumed successfully
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/export:
    get:
      operationId: exportAllFunctions
      summary: Export all Eventing Functions
      description: >-
        Exports all Eventing Function definitions. Exported functions are
        always set to undeployed state at the time of export.
      tags:
        - Import Export
      responses:
        '200':
          description: Functions exported successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventingFunction'
        '401':
          description: Unauthorized access
  /api/v1/export/{functionName}:
    get:
      operationId: exportEventingFunction
      summary: Export a specific Eventing Function
      description: >-
        Exports the definition of a specific Eventing Function in undeployed
        state.
      tags:
        - Import Export
      parameters:
        - $ref: '#/components/parameters/functionName'
      responses:
        '200':
          description: Function exported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventingFunction'
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/import:
    post:
      operationId: importFunctions
      summary: Import Eventing Functions
      description: >-
        Imports Eventing Function definitions. Imported functions always start
        in undeployed state regardless of the setting values in the import data.
      tags:
        - Import Export
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EventingFunction'
      responses:
        '200':
          description: Functions imported successfully
        '400':
          description: Invalid function definitions
        '401':
          description: Unauthorized access
  /api/v1/status:
    get:
      operationId: getEventingStatus
      summary: Get Eventing Service status
      description: >-
        Returns the deployment status and processing status of all Eventing
        Functions.
      tags:
        - Statistics
      responses:
        '200':
          description: Successful retrieval of Eventing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventingStatus'
        '401':
          description: Unauthorized access
  /api/v1/stats:
    get:
      operationId: getEventingStats
      summary: Get Eventing Function statistics
      description: >-
        Returns execution statistics for all Eventing Functions including
        mutation processing counts, failure counts, and timing information.
      tags:
        - Statistics
      responses:
        '200':
          description: Successful retrieval of function statistics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventingFunctionStats'
        '401':
          description: Unauthorized access
  /api/v1/functions/{functionName}/applog:
    get:
      operationId: getEventingFunctionLog
      summary: Get Eventing Function application log
      description: >-
        Returns the most recent application log messages generated by the
        specified Eventing Function via the log() function in handler code.
      tags:
        - Logging
      parameters:
        - $ref: '#/components/parameters/functionName'
        - name: aggregate
          in: query
          required: false
          description: Whether to aggregate logs from all nodes
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Successful retrieval of application log
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized access
        '404':
          description: Function not found
  /api/v1/config:
    get:
      operationId: getEventingConfig
      summary: Get Eventing Service configuration
      description: >-
        Returns the current configuration settings for the Eventing Service.
      tags:
        - Configuration
      responses:
        '200':
          description: Successful retrieval of Eventing configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventingConfig'
        '401':
          description: Unauthorized access
    post:
      operationId: updateEventingConfig
      summary: Update Eventing Service configuration
      description: >-
        Updates the configuration settings for the Eventing Service.
      tags:
        - Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventingConfig'
      responses:
        '200':
          description: Configuration updated successfully
        '400':
          description: Invalid configuration
        '401':
          description: Unauthorized access
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using Couchbase Server credentials.
  parameters:
    functionName:
      name: functionName
      in: path
      required: true
      description: The name of the Eventing Function
      schema:
        type: string
  schemas:
    EventingFunction:
      type: object
      description: Eventing Function definition
      required:
        - appname
        - appcode
      properties:
        appname:
          type: string
          description: Name of the Eventing Function
        appcode:
          type: string
          description: JavaScript handler code for the function
        depcfg:
          type: object
          description: Dependency configuration including bindings
          properties:
            buckets:
              type: array
              description: Bucket bindings for the function
              items:
                type: object
                properties:
                  alias:
                    type: string
                    description: Alias name used in handler code
                  bucket_name:
                    type: string
                    description: Name of the bound bucket
                  scope_name:
                    type: string
                    description: Name of the scope
                  collection_name:
                    type: string
                    description: Name of the collection
                  access:
                    type: string
                    description: Access level for the bucket binding
                    enum:
                      - r
                      - rw
            curl:
              type: array
              description: cURL bindings for external HTTP calls
              items:
                type: object
                properties:
                  hostname:
                    type: string
                    description: URL of the external endpoint
                  value:
                    type: string
                    description: Alias name used in handler code
                  auth_type:
                    type: string
                    description: Authentication type
                    enum:
                      - no-auth
                      - basic
                      - bearer
                      - digest
                  allow_cookies:
                    type: boolean
                    description: Whether to allow cookies
                  validate_ssl_certificate:
                    type: boolean
                    description: Whether to validate SSL certificates
            constants:
              type: array
              description: Constant bindings
              items:
                type: object
                properties:
                  value:
                    type: string
                    description: Alias name
                  literal:
                    type: string
                    description: Constant value
            source_bucket:
              type: string
              description: Source bucket for mutations
            source_scope:
              type: string
              description: Source scope for mutations
            source_collection:
              type: string
              description: Source collection for mutations
            metadata_bucket:
              type: string
              description: Metadata bucket for checkpoints
            metadata_scope:
              type: string
              description: Metadata scope for checkpoints
            metadata_collection:
              type: string
              description: Metadata collection for checkpoints
        settings:
          type: object
          description: Function deployment settings
          properties:
            dcp_stream_boundary:
              type: string
              description: Starting point for processing mutations
              enum:
                - everything
                - from_now
            deployment_status:
              type: boolean
              description: Whether the function is deployed
            processing_status:
              type: boolean
              description: Whether the function is processing mutations
            log_level:
              type: string
              description: Log level for the function
              enum:
                - INFO
                - ERROR
                - WARNING
                - DEBUG
                - TRACE
            language_compatibility:
              type: string
              description: Language compatibility version
            execution_timeout:
              type: integer
              description: >-
                Maximum execution time for a single handler invocation in
                seconds
            timer_context_size:
              type: integer
              description: Maximum size of timer context in bytes
            worker_count:
              type: integer
              description: Number of worker threads
            num_timer_partitions:
              type: integer
              description: Number of timer partitions
        function_scope:
          type: object
          description: Scope of the function definition
          properties:
            bucket:
              type: string
              description: Bucket for the function scope
            scope:
              type: string
              description: Scope name
    EventingStatus:
      type: object
      description: Status of all Eventing Functions
      properties:
        num_eventing_nodes:
          type: integer
          description: Number of nodes running the Eventing service
        apps:
          type: array
          description: Status of each Eventing Function
          items:
            type: object
            properties:
              name:
                type: string
                description: Function name
              composite_status:
                type: string
                description: Overall status of the function
                enum:
                  - undeployed
                  - deploying
                  - deployed
                  - undeploying
                  - paused
                  - pausing
              deployment_status:
                type: boolean
                description: Whether the function is deployed
              processing_status:
                type: boolean
                description: Whether the function is processing
              num_deployed_nodes:
                type: integer
                description: Number of nodes where the function is deployed
              function_scope:
                type: object
                description: Scope of the function
                properties:
                  bucket:
                    type: string
                  scope:
                    type: string
    EventingFunctionStats:
      type: object
      description: Execution statistics for an Eventing Function
      properties:
        function_name:
          type: string
          description: Name of the function
        execution_stats:
          type: object
          description: Execution statistics
          properties:
            on_update_success:
              type: integer
              description: Successful OnUpdate handler invocations
            on_update_failure:
              type: integer
              description: Failed OnUpdate handler invocations
            on_delete_success:
              type: integer
              description: Successful OnDelete handler invocations
            on_delete_failure:
              type: integer
              description: Failed OnDelete handler invocations
            timer_callback_success:
              type: integer
              description: Successful timer callback invocations
            timer_callback_failure:
              type: integer
              description: Failed timer callback invocations
        failure_stats:
          type: object
          description: Failure statistics
          properties:
            timeout_count:
              type: integer
              description: Number of handler timeouts
            n1ql_op_exception_count:
              type: integer
              description: Number of N1QL operation exceptions
    EventingConfig:
      type: object
      description: Eventing Service configuration
      properties:
        enable_debugger:
          type: boolean
          description: Whether the debugger is enabled
        ram_quota:
          type: integer
          description: RAM quota for the Eventing service in megabytes