Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Eventing REST API

  • reference
    +

    Overview

    The Eventing REST API provides methods to work with and manipulate Couchbase Eventing functions.

    Version information

    Version : 7.6

    Host information

    {scheme}://{host}:{port}

    The URL scheme, host, and port are as follows.

    Component Description

    scheme

    The URL scheme. Use https for secure access.

    Values: http, https
    Example: http

    host

    The host name or IP address of a node running the Eventing service.

    Example: localhost

    port

    The Eventing service REST port. Use 18096 for secure access.

    Values: 8096, 18096
    Example: 8096

    Examples on this page

    In the HTTP request examples:

    • $HOST is the host name or IP address of a node running the Eventing service.

    • $ADMIN is the user name of an administrator — see Security.

    • $USER is the user name of any authorized user — see Security.

    • $PASSWORD is the password to connect to Couchbase Server.

    Resources

    This section describes the operations available with this REST API. The operations are grouped in the following categories.

    Activation
    Advanced
    Global Config
    List
    Logging
    Statistics
    Status

    Activation

    Table of Contents

    Deploy a Function
    Pause a Function
    Resume a Function
    Undeploy a Function

    Deploy a Function

    POST /api/v1/functions/{function}/deploy
    Description

    Deploys an undeployed function. This is the preferred invocation.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Deploy a global function
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/deploy"
    Deploy a scoped function
    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/deploy?bucket=bulk&scope=data"

    Pause a Function

    POST /api/v1/functions/{function}/pause
    Description

    Pauses a function and creates a DCP checkpoint such that on a subsequent resume no mutations will be lost. This is the preferred invocation.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Pause a global function
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/pause"
    Pause a scoped function
    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/pause?bucket=bulk&scope=data"

    Resume a Function

    POST /api/v1/functions/(function}/resume
    Description

    Resumes a paused function from its paused DCP checkpoint. This is the preferred invocation.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Resume a global function
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/resume"
    Resume a scoped function
    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/resume?bucket=bulk&scope=data"

    Undeploy a Function

    POST /api/v1/functions/{function}/undeploy
    Description

    Undeploys a function. This is the preferred invocation.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Undeploy a global function
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/undeploy"
    Undeploy a scoped function
    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/undeploy?bucket=bulk&scope=data"

    Advanced

    Table of Contents

    Create or Import a Function
    Create or Import Multiple Functions
    View a Function
    View Multiple Functions
    Delete Function
    Delete Multiple Functions
    Export Multiple Functions
    Import Multiple Functions
    View Function Settings
    Update Function Settings
    View Function Config
    Update Function Config
    View Function Code
    Update Function Code

    Create or Import a Function

    POST /api/v1/functions/{function}
    Description

    Creates or imports a single function.

    Consumes

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Body Parameter

    Name Description Schema

    Body
    required

    A single function definition object, or an array containing a single function definition object. The function name in the definition object must match that given by the path parameter.

    Function Request
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Import a global function
    Curl request
    curl -XPOST -d @./my_function.json \
  "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function"
    Import a scoped function
    Curl request
    curl -XPOST -d @./my_function.json \
  "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function?bucket=bulk&scope=data"

    Create or Import Multiple Functions

    POST /api/v1/functions
    Description

    Creates or imports multiple functions.

    Note that if any function's language_compatibility field is missing, the value will be set to the highest version supported by the server, unlike Import Multiple Functions.

    Consumes

    • application/json

    Parameters
    Body Parameter

    Name Description Schema

    Body
    required

    A single function definition object, or an array containing one or more function definition objects. Function names must be unique. When multiple functions have the same name, an error is reported.

    Functions Request
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    Import multiple functions
    Curl request
    curl -XPOST -d @./array_of_functions.json \
  "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions"

    View a Function

    GET /api/v1/functions/{function}
    Description

    Provides a listing of a complete function definition available in the cluster. The function could be in any state: deployed, undeployed, or paused. If saved to a file the function definition can be imported into the cluster or a different cluster. However any changes to the function definition made to the file outside the UI are discouraged.

    Produces

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Returns a single function definition object.

    Function Definition

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View a global function definition
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function"
    View a scoped function definition
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function?bucket=bulk&scope=data"
    Save a global function definition to file
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function" \
  -o my_function.json
    Save a scoped function definition to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function?bucket=bulk&scope=data" \
  -o my_function.json

    View Multiple Functions

    GET /api/v1/functions
    Description

    Provides an array of definitions of all functions available in the cluster. The functions may be in any state: deployed, undeployed, or paused. If saved to a file the function definitions can be imported into the cluster or a different cluster. However any changes to the function definition made to the file outside the UI are discouraged.

    If this API is run as a non-Administrator, the results are filtered via RBAC to include only the function scopes the user has access to.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    Returns an array containing one or more function definition objects.

    Function Definition array

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    View all function definitions
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions"
    Save all function definitions to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions" \
  -o array_of_functions.json

    Delete Function

    DELETE /api/v1/functions/{function}
    Description

    Deletes a specific function from the cluster.

    WARNING: Use this API with caution, as it is irreversible.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Delete a global function
    Curl request
    curl -XDELETE "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function"
    Delete a scoped function
    Curl request
    curl -XDELETE "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function?bucket=bulk&scope=data"

    Delete Multiple Functions

    DELETE /api/v1/functions
    Description

    Deletes all functions from the cluster. WARNING: Use this API with caution, as it is irreversible.

    If this API is run as a non-Administrator the deleted set will be filtered via RBAC to include only the function scopes the user has access to.

    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Request
    Delete all functions
    Curl request
    curl -XDELETE "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions"

    Export Multiple Functions

    GET /api/v1/export
    Description

    This is a convenience method to export all function definitions. Exported functions are always set to the undeployed state at the time of export, regardless of their state in the cluster. If saved to a file the function definitions can be imported into the cluster or a different cluster. However any changes to the function definition made to the file outside the UI are discouraged.

    If this API is run as a non-Administrator the results are filtered via RBAC to include only the function scopes the user has access to.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    Returns an array containing one or more function definition objects.

    Function Definition array

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    View all function definitions
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/export"
    Save all function definitions to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/export" \
  -o array_of_functions.json

    Import Multiple Functions

    POST /api/v1/import
    Description

    Imports multiple functions.

    Note that if any function's language_compatibility field is missing, the value will be set to 6.0.0, unlike Create or Import Multiple Functions.

    Consumes

    • application/json

    Parameters
    Body Parameter

    Name Description Schema

    Body
    required

    A single function definition object, or an array containing one or more function definition objects. Function names must be unique. When multiple functions have the same name, an error is reported.

    Functions Request
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    Import multiple functions
    Curl request
    curl -XPOST -d @./array_of_functions.json \
  "http://$USER:$PASSWORD@$HOST:8096/api/v1/import"

    View Function Settings

    GET /api/v1/functions/{function}/settings
    Description

    Return or export the full settings for one eventing function in the cluster. The settings can be subsequently imported. However any changes to the function settings made to the file outside the UI are discouraged.

    Produces

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Returns an object showing settings for the specified function.

    Function Settings

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View global function settings
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
    View scoped function settings
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
    Save global function settings to file
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings" \
  -o my_function.json
    Save scoped function settings to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data" \
  -o my_function.json

    Update Function Settings

    POST /api/v1/functions/{function}/settings
    Description

    Updates an undeployed or paused function with the provided settings. You can only alter settings when the function is paused or undeployed; attempting to adjust a deployed function will result in an error. During an edit, settings provided are merged. Unspecified attributes retain their prior values.

    Note that you must always specify deployment_status and processing_status when using this REST endpoint to update any option or set of options. To get the current values of deployment_status and processing_status, see View All Functions Status or View Function Status.

    By adjusting deployment_status and processing_status this command can also deploy or resume a function; however, it cannot pause or undeploy a function.

    Consumes

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Body Parameter

    Name Description Schema

    Body
    required

    An object providing settings for the specified function.

    Function Settings
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Update global function settings

    This example updates the worker_count setting.

    Curl request
    curl -XPOST -d '{
  "deployment_status": false,
  "processing_status": false,
  "worker_count": 6
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
    Update scoped function settings

    This example updates the worker_count setting.

    Curl request
    curl -XPOST -d '{
  "deployment_status": false,
  "processing_status": false,
  "worker_count": 6
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
    Update undeployed global function settings

    This example updates the app_log_max_files and app_log_max_size settings. The function is currently undeployed.

    Curl request
    curl -XPOST -d '{
  "deployment_status": false,
  "processing_status": false,
  "app_log_max_files": 5
  "app_log_max_size":10485760
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
    Update undeployed scoped function settings

    This example updates the app_log_max_files and app_log_max_size settings. The function is currently undeployed.

    Curl request
    curl -XPOST -d '{
  "deployment_status": false,
  "processing_status": false,
  "app_log_max_files": 5,
  "app_log_max_size": 10485760
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
    Update paused global function settings

    This example updates the timer_context_size setting. The function is currently paused.

    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": false,
  "timer_context_size": 2048
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
    Update paused scoped function settings

    This example updates the timer_context_size setting. The function is currently paused.

    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": false,
  "timer_context_size": 2048
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
    Update paused global function settings and resume

    This example updates the worker_count setting and resumes. The function is currently paused.

    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": true,
  "worker_count": 8
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
    Update paused scoped function settings and resume

    This example updates the worker_count setting and resumes. The function is currently paused.

    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": true,
  "worker_count": 8
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
    Deploy an undeployed global function — deprecated
    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": true
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"

    Deprecated. See Deploy a Function for the preferred invocation.

    Deploy an undeployed scoped function — deprecated
    Curl request
    curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": true
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"

    Deprecated. See Deploy a Function for the preferred invocation.

    View Function Config

    GET /api/v1/functions/{function}/config
    Description

    Export or return the configuration of the source keyspace and the eventing storage (metadata) keyspace for the specified function. The definition can be subsequently imported. However any changes to the function definition made to the file outside the UI are discouraged.

    Produces

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Returns an object showing the configuration of the specified function.

    Deployment Config

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View global function config
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config"
    View scoped function config
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config?bucket=bulk&scope=data"
    Save global function config to file
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config" \
  -o my_function.json
    Save scoped function config to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config?bucket=bulk&scope=data" \
  -o my_function.json

    Update Function Config

    POST /api/v1/functions/{function}/config
    Description

    Import the configuration and alter the source keyspace and the eventing storage (metadata) keyspace for the specified function. You can only change these values if a function is in the undeployed state and the two keyspaces exist.

    Consumes

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Body Parameter

    Name Description Schema

    Body
    required

    An object providing the configuration for the specified function.

    Deployment Config
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Update global function config

    This example alters the source and eventing storage keyspaces.

    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config" \
  -d '{
  "source_bucket": "bulk",
  "source_scope": "orders",
  "source_collection": "customer01",
  "metadata_bucket": "rr100",
  "metadata_scope": "eventing",
  "metadata_collection": "metadata"
}'
    Update scoped function config

    This example alters the source and eventing storage keyspaces.

    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config?bucket=bulk&scope=data"\
  -d '{
  "source_bucket": "bulk",
  "source_scope": "orders",
  "source_collection": "customer01",
  "metadata_bucket": "rr100",
  "metadata_scope": "eventing",
  "metadata_collection": "metadata"
}'
    Update global function config from file

    This example alters the source and eventing storage keyspaces from a file.

    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config" \
  -d @./my_function.json
    Update scoped function config from file

    This example alters the source and eventing storage keyspaces from a file.

    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/config?bucket=bulk&scope=data" \
  -d @./my_function.json

    View Function Code

    GET /api/v1/functions/{function}/appcode
    Description

    Export only the JavaScript code for the specified function. Note that unlike View a Function, the JavaScript is not escaped, and the code is runnable in other environments. The JavaScript code can be subsequently imported. However any changes to the function definition made to the file outside the UI are discouraged.

    Produces

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Returns a string showing the code for the specified function.

    String

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View global function code
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode"
    View scoped function code
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode?bucket=bulk&scope=data"
    Save global function code to file
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode" \
  -o my_function.json
    Save scoped function code to file
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode?bucket=bulk&scope=data" \
  -o my_function.json

    Update Function Code

    POST /api/v1/functions/{function}/appcode
    Description

    Import only the JavaScript code for the specified function. Note that unlike Create or Import Function, the JavaScript is not escaped and could come from other environments. It is highly recommended that you use the flag --data-binary or --upload-file when importing your JavaScript appcode fragments to avoid potential encoding issues due to string escaping.

    Consumes

    • application/json

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Body Parameter

    Name Description Schema

    Body
    required

    A string providing the code for the specified function.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Update global function code
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode" \
  --data-binary 'function OnUpdate(doc, meta) { log("id",meta.id); }'
    Update scoped function code
    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/appcode?bucket=bulk&scope=data" \
  --data-binary 'function OnUpdate(doc, meta) { log("id",meta.id); }'
    Update global function code from file

    This example uses the --data-binary option. Do not use -d.

    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/import" \
  --data-binary @./my_function.json
    Update scoped function code from file

    This example uses the --data-binary option. Do not use -d.

    Curl request
    curl -XPOST "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/import?bucket=bulk&scope=data" \
  --data-binary @./my_function.json
    Update global function code from file — alternative

    This example uses the --upload-file option.

    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/import" \
  --upload-file ./my_function.json
    Update scoped function code from file — alternative

    This example uses the --upload-file option.

    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/import?bucket=bulk&scope=data" \
  --upload-file ./my_function.json

    Global Config

    Table of Contents

    List Global Config
    Modify Global Config

    List Global Config

    GET /api/v1/config
    Description

    Shows all global configuration settings. There are currently just two settings: enable_debugger and ram_quota. Both of these settings can also be adjusted via the UI.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    Returns an object showing the global configuration settings.

    Global Config

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    View global configuration
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config"

    Modify Global Config

    POST /api/v1/config
    Description

    Modify global configuration settings. During an edit, settings provided are merged. Unspecified attributes retain their prior values. The response indicates whether the Eventing service must be restarted for the new changes to take effect.

    Consumes

    • application/json

    Interbucket Recursion

    If you need to turn off infinite recursion protection for Eventing functions, you can use an alternative REST API endpoint to enable interbucket recursion. For details, see Troubleshooting and Best Practices.

    Allowing interbucket recursion is highly discouraged unless you have an advanced use case and follow strict non-production coding and verification.
    Parameters
    Body Parameter

    Name Description Schema

    Body
    required

    An object providing the global configuration settings.

    Global Config
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    Alter RAM quota
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config" \
  -d '{"ram_quota": 512}'
    Enable debugger
    Curl request
    curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config" \
  -d '{"enable_debugger": true}'
    Allow interbucket recursion

    This example disables the safety checks that prevent basic infinite recursive Eventing functions.

    Curl request
    curl -X POST -u $ADMIN:$PASSWORD "http://$HOST:8091/_p/event/api/v1/config" \
  -d '{"allow_interbucket_recursion": true}'
    Disallow interbucket recursion

    This example restores the default setting, which applies some sanity checks to prevent basic infinite recursive Eventing functions.

    Curl request
    curl -X POST -u $ADMIN:$PASSWORD "http://$HOST:8091/_p/event/api/v1/config"
  -d '{"allow_interbucket_recursion": false}'

    List

    Table of Contents

    List All Functions
    List Filtered Functions

    List All Functions

    GET /api/v1/list/functions
    Description

    Returns a list (array) of the names of all Eventing functions in the cluster. The returned list can also be filtered — see List Filtered Functions.

    If this API is run as a non-Administrator the results are filtered via RBAC to include only the function scopes the user has access to.

    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    List all functions
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/list/functions"

    List Filtered Functions

    GET /api/v1/list/functions/query
    Description

    Returns a list (array) of the names of all Eventing functions in the cluster. The returned list can be filtered by the following:

    • Deployed status : in this case, paused is considered deployed.
    • Source bucket: the listen to keyspace.
    • Function type: whether the function modifies its own listen to keyspace.

    If this API is run as a non-Administrator the results are filtered via RBAC to include only the function scopes the user has access to.

    Parameters
    Query Parameters

    Name Description Schema

    deployed
    optional

    If true, returns the names of all deployed (or paused) functions. If false, returns the names of all undeployed functions.

    Boolean

    source_bucket
    optional

    The name of a bucket. Returns the names of Eventing functions in the cluster that have a source keyspace under the specified bucket.

    String

    function_type
    optional

    The function type.

    • sbm: Returns the names of Eventing functions in the cluster that modify their own source keyspace.
    • notsbm: Returns the names of Eventing functions in the cluster that do not modify their own source keyspace.

    Values: "sbm", "notsbm"

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    List all deployed functions
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/list/functions/query?deployed=true"

    If you had specified deployed=false, you would get all undeployed functions.

    List all functions with source keyspace in a specific bucket
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/list/functions/query?source_bucket=bulk"
    List all functions that do not modify their source keyspace
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/list/functions/query?function_type=notsbm"

    Logging

    Table of Contents

    Get Log for a Function

    Get Log for a Function

    GET /getAppLog
    Description

    Returns the most recent application log messages for the specified function.

    Parameters
    Query Parameters

    Name Description Schema

    name
    required

    The name of a function.

    String

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String

    aggregate
    optional

    If false, the API accesses a single Eventing node. If true, the API accesses all Eventing nodes.

    Default: false

    Boolean

    size
    optional

    The approximate amount of logging information returned. Note that when fetching from more than one Eventing node, the amount of logging information returned from each node is the size divided by the number of nodes.

    Default: 40960

    Integer
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View global function log from a single node
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getAppLog?name=my_function"
    View scoped function log from a single node
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getAppLog?name=my_function&bucket=bulk&scope=data"
    View global function log from all Eventing nodes
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getAppLog?name=my_function&aggregate=true"
    View scoped function log from all Eventing nodes
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getAppLog?name=my_function&aggregate=true&bucket=bulk&scope=data"
    View size-limited global function log

    This example fetches recent Application log info from all Eventing nodes, limited to 2048 bytes.

    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getAppLog?name=my_function&aggregate=true&size=2048"
    View size-limited scoped function log

    This example fetches recent Application log info from all Eventing nodes, limited to 2048 bytes.

    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getAppLog?name=my_function&aggregate=true&size=2048&bucket=bulk&scope=data"

    Statistics

    Table of Contents

    Get All Statistics
    Get Execution Statistics
    Get Failure Statistics
    Get Latency Statistics
    Reset Statistics

    Get All Statistics

    GET /api/v1/stats
    Description

    Retrieve all statistics for the node.

    If this API is run as a non-Administrator the results are filtered via RBAC to include only the function scopes the user has access to.

    Parameters
    Query Parameters

    Name Description Schema

    type
    optional

    Including this parameter returns the full statistics set, inclusive of events processing, events remaining, execution, failure, latency, worker PIDs and sequence processed.

    Omitting this parameter excludes dcp_event_backlog_per_vb, doc_timer_debug_stats, latency_stats, plasma_stats, and seqs_processed from the response.

    Values: "full"

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    Get basic statistics
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/stats"
    Get full statistics
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/stats?type=full"

    Get Execution Statistics

    GET /getExecutionStats
    Description

    Retrieve only execution statistics. This returns the subset of statistics for the node.

    Parameters
    Query Parameters

    Name Description Schema

    name
    required

    The name of a function.

    String

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View execution statistics for global function
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getExecutionStats?name=my_function"
    View execution statistics for scoped function
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getExecutionStats?name=my_function&bucket=bulk&scope=data"

    Get Failure Statistics

    GET /getFailureStats
    Description

    Retrieve only failure statistics. This returns the subset of statistics for the node.

    Parameters
    Query Parameters

    Name Description Schema

    name
    required

    The name of a function.

    String

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View failure statistics for global function
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getFailureStats?name=my_function"
    View failure statistics for scoped function
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getFailureStats?name=my_function&bucket=bulk&scope=data"

    Get Latency Statistics

    GET /getLatencyStats
    Description

    Retrieve only latency statistics. This returns the subset of statistics for the node.

    Parameters
    Query Parameters

    Name Description Schema

    name
    required

    The name of a function.

    String

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View latency statistics for global function
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/getLatencyStats?name=my_function"
    View latency statistics for scoped function
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/getLatencyStats?name=my_function&bucket=bulk&scope=data"

    Reset Statistics

    GET /resetStatsCounters
    Description

    Resets statistics for the specified function.

    Parameters
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String

    appName
    required

    The name of a function.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    Reset statistics for global function
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/resetStatsCounters?appName=my_function"
    Reset statistics for scoped function
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/resetStatsCounters?appName=my_function&bucket=bulk&scope=data"

    Status

    Table of Contents

    View All Functions Status
    View Function Status

    View All Functions Status

    GET /api/v1/status
    Description

    Returns a list (array) of all eventing functions, showing their corresponding composite_status. A function's status can have one of the following values: undeployed, deploying, deployed, undeploying, paused, and pausing. Note that there is no value of resuming; when resuming a paused eventing function, the composite_status returns deploying until it reaches the deployed state.

    If this API is run as a non-Administrator, the results are filtered via RBAC to include only the function scopes the user has access to.

    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Unscoped
    Example HTTP Requests
    View status of all functions
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/status"

    View Function Status

    GET /api/v1/status/{function}
    Description

    Returns the specified function, showing its corresponding composite_status. It can have one of the following values: undeployed, deploying, deployed, undeploying, paused, and pausing. Note that there is no value of resuming; when resuming a paused eventing function, the composite_status returns deploying until it reaches the deployed state.

    Parameters
    Path Parameters

    Name Description Schema

    function
    required

    The name of a function.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

    For scoped functions only. The bucket to which the function belongs.

    String

    scope
    optional

    For scoped functions only. The scope to which the function belongs.

    String
    Responses
    HTTP Code Description Schema

    200

    Success.

    404

    Failure.
    Security
    Type Name

    http (basic)

    Scoped

    http (basic)

    Global
    Example HTTP Requests
    View global function status
    Curl request
    curl -XGET "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/status/my_function"
    View scoped function status
    Curl request
    curl -XGET "http://$USER:$PASSWORD@$HOST:8096/api/v1/status/my_function?bucket=bulk&scope=data"

    Definitions

    This section describes the properties consumed and returned by this REST API.

    Function Request
    Functions Request
    Deployment Config
    Deployment Constants
    Deployment Keyspace
    Deployment URL
    Function Definition
    Function Scope
    Function Settings
    Global Config

    Changes to the Eventing function definition files made outside of this REST API or the interactive UI are only supported if you adhere to the Eventing schemas described here.

    Function Request

    Composite Schema

    One of the following:

    Functions Request

    Composite Schema

    One of the following:

    Deployment Config

    Object

    Property Schema

    buckets
    optional

    Deployment Keyspace array

    curl
    optional

    Deployment URL array

    metadata_bucket
    required

    bucket to store eventing checkpoints and timers

    Minimum length: 1

    String

    metadata_scope
    optional

    scope to store eventing checkpoints and timers

    String

    metadata_collection
    optional

    collection to store eventing checkpoints and timers

    String

    source_bucket
    required

    bucket to listen to for document mutations

    Minimum length: 1

    String

    source_scope
    optional

    scope to listen to for document mutations

    String

    source_collection
    optional

    collection to listen to for document mutations

    String

    constants
    optional

    Deployment Constants array

    Deployment Constants

    Object

    Property Schema

    value
    required

    alias name of the constant binding

    Pattern: /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
    Minimum length: 1
    Maximum length: 64

    String

    literal
    required

    literal value bound to the alias name

    Minimum length: 1

    String

    Deployment Keyspace

    Object

    Property Schema

    alias
    required

    symbolic name used in code to refer to this binding

    Pattern: /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
    Minimum length: 1
    Maximum length: 64

    String

    bucket_name
    required

    name of the bucket this binding maps to

    Minimum length: 1

    String

    scope_name
    optional

    name of the scope this binding maps to

    String

    collection_name
    optional

    name of the collection this binding maps to

    String

    access
    required

    bucket access level (read or read+write)

    Values: "r", "rw"

    String

    Deployment URL

    Object

    Property Schema

    hostname
    required

    full URL (including any path) that this binding connects

    Pattern: /^https?:\/\//
    Minimum length: 1

    URI (uri)

    value
    required

    symbolic name used in code to refer to this binding

    Pattern: /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
    Minimum length: 1
    Maximum length: 64

    String

    auth_type
    required

    http authentication method to use with this endpoint

    Values: "no-auth", "basic", "bearer", "digest"

    String

    username
    optional

    username for http auth methods that use it

    String

    password
    optional

    password for http auth methods that use it

    String

    bearer_key
    optional

    bearer key for bearer auth

    String

    allow_cookies
    required

    allow cookies on the session

    Boolean

    validate_ssl_certificate
    required

    validate remote server certificate using OS mechanisms

    Boolean

    Function Definition

    Object

    Property Schema

    appcode
    required

    handler code

    Minimum length: 1

    String

    depcfg
    required

    deployment configuration

    Deployment Config

    version
    required

    authoring tool. use 'external' if authored or edited outside eventing ui

    Pattern: /^evt-[5-7].[0-9]+.[0-9]+-[0-9]{4}-(ee|ce)$/

    String

    enforce_schema
    optional

    enforces stricter validation for all settings and configuration fields.

    Boolean

    handleruuid
    optional

    unique id of the the handler. generated by server

    Minimum: 0

    Integer

    function_instance_id
    optional

    unique id of the deployment of the handler. generated by server

    Minimum length: 0

    String

    appname
    required

    Pattern: /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/
    Minimum length: 1
    Maximum length: 100

    String

    settings
    required

    Function Settings

    function_scope
    optional

    function scope

    Function Scope

    Function Scope

    Object

    Property Schema

    bucket
    required

    bucket to which function belongs

    Minimum length: 1

    String

    scope
    required

    scope to which function belongs

    Minimum length: 1

    String

    Function Settings

    Object

    Property Schema

    cpp_worker_thread_count
    optional

    number of threads each worker utilizes

    Minimum: 1

    Integer

    dcp_stream_boundary
    optional

    indicates where to start dcp stream from (beginning of time, present point) 'from_prior' is deprecated in 6.6.2

    Values: "everything", "from_now"

    String

    deployment_status
    optional

    indicates if the function is deployed. true=deployed, false=undeployed

    Boolean

    description
    optional

    free form text for user to describe the handler. no functional role

    String

    execution_timeout
    optional

    maximum time the handler can run before it is forcefully terminated (in seconds)

    Minimum: 1

    Integer

    language_compatibility
    optional

    eventing language version this handler assumes in terms of syntax and behavior

    Values: "6.6.2", "6.0.0", "6.5.0", "7.2.0"

    String

    lcb_inst_capacity
    optional

    maximum number of libcouchbase connections that may be opened and pooled

    Minimum: 1

    Integer

    lcb_retry_count
    optional

    number of retries of retriable libcouchbase failures. 0 keeps trying till execution_timeout

    Minimum: 0

    Integer

    lcb_timeout
    optional

    maximum time the lcb command is waited until completion before we terminate the request(in seconds)

    Minimum: 1

    Integer

    log_level
    optional

    level of detail in system logging

    Values: "INFO", "ERROR", "WARNING", "DEBUG", "TRACE"

    String

    n1ql_consistency
    optional

    consistency level used by n1ql statements in the handler

    Values: "none", "request"

    String

    num_timer_partitions
    optional

    number of timer shards. defaults to number of vbuckets

    Values: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024

    Integer

    processing_status
    optional

    indicates if the function is running (i.e., not paused). true=running, false=paused

    Boolean

    sock_batch_size
    optional

    batch size for messages from producer to consumer. normally, this must not be specified

    Minimum: 1

    Integer

    tick_duration
    optional

    duration to log stats from this handler, in milliseconds

    Integer

    timer_context_size
    optional

    size limit of timer context object

    Minimum: 20
    Maximum: 20971520

    Integer

    user_prefix
    optional

    key prefix for all data stored in metadata by this handler

    Minimum length: 1

    String

    worker_count
    optional

    number of worker processes handler utilizes on each eventing node

    Minimum: 1

    Integer

    n1ql_prepare_all
    optional

    automatically prepare all n1ql statements in the handler

    Boolean

    handler_headers
    optional

    code to automatically prepend to top of handler code

    String array

    handler_footers
    optional

    code to automatically append to bottom of handler code

    String array

    enable_applog_rotation
    optional

    enable rotating this handlers log() message files

    Boolean

    app_log_dir
    optional

    directory to write content of log() message files

    String

    app_log_max_size
    optional

    rotate logs when file grows to this size in bytes approximately

    Minimum: 1024

    Integer

    app_log_max_files
    optional

    number of log() message files to retain when rotating

    Minimum: 1

    Integer

    checkpoint_interval
    optional

    number of seconds before writing a progress checkpoint

    Minimum: 1

    Integer

    bucket_cache_size
    optional

    maximum size in bytes the bucket cache can grow to

    Minimum: 20971520

    Integer

    bucket_cache_age
    optional

    time in milliseconds after which a cached bucket object is considered stale

    Minimum: 1

    Integer

    curl_max_allowed_resp_size
    optional

    maximum allowable curl call response in 'MegaBytes'. Setting the value to 0 lifts the upper limit off. This parameters affects v8 engine stability since it defines the maximum amount of heap space acquired by a curl call

    Integer

    Global Config

    Object

    Property Schema

    ram_quota
    optional

    The memory allocation for the Eventing Service, per node.

    Default: 256
    Example: 512

    Integer

    enable_debugger
    optional

    Enables the Eventing service debugger. For details, see Debugging and Diagnosability.

    Default: false

    Boolean

    Security

    The Eventing REST APIs support HTTP basic authentication. Credentials can be passed via HTTP headers.

    Global

    Global functions with a function scope of *.* can only be made or managed by users with the Full Admin or Eventing Full Admin role. For global functions, you do not need to pass the bucket and scope query parameters to specify the function scope. The credentials must be an administrator username and password.

    Note that this is the default function scope for all functions after an upgrade from a prior version.

    Type : http

    Scoped

    For scoped functions, you must pass the bucket and scope query parameters to specify the function scope. The credentials are the username and password of any authorized user.

    You can quote the REST call on the command line to escape the & and ? characters.

    Type : http

    Unscoped

    Unscoped REST API calls do not require you to specify the function scope. The action is fully determined by the username and password credentials passed to the REST call.

    Type : http

    Refer to Eventing Role-Based Access Control (RBAC) for more details.