March 9, 2025
+ 12

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

Table of Contents

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

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.

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.

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.

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.

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.

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.

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.

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.

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"
Enable Sync Gateway compatibility for a global function

Couchbase Server 7.6.4

This example sets allow_sync_documents to false, to enable compatibility with Sync Gateway. The function is currently paused.

Curl request
curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": false,
  "allow_sync_documents": false
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
Enable Sync Gateway compatibility for a scoped function

Couchbase Server 7.6.4

This example sets allow_sync_documents to false, to enable compatibility with Sync Gateway. The function is currently paused.

Curl request
curl -XPOST -d '{
  "deployment_status": true,
  "processing_status": false,
  "allow_sync_documents": false
}' "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.

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.

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

GET /api/v1/config
Description

Shows all global configuration settings. Note that the enable_debugger and ram_quota 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.

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.

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}'
Set cursor limit

Couchbase Server 7.6.4

Curl request
curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config" \
  -d '{"cursor_limit": 10}'
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

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 /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 /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

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.

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

curl
optional

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

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

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_scope
optional

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

cursor_checkpoint_timeout
optional

Couchbase Server 7.6.4

The maximum time the checkpoint writer can run before it is forcefully terminated (in seconds).

Minimum: 1

Integer

on_deploy_timeout
optional

maximum time the OnDeploy handler can run before it is 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

allow_transaction_mutations
optional

allow staged transaction mutations

Boolean

allow_sync_documents
optional

Couchbase Server 7.6.4

Specifies whether the function allows Sync Gateway mutations.

  • By default, this setting is true, for compatibility with previous versions of Couchbase Server.

  • When this setting is false, the specified function skips all internal Sync Gateway documents, whose IDs are prefixed with _sync. This enables the function to work with Sync Gateway.

You must ensure that none of the documents which contain your own working data have IDs which are prefixed with _sync. (Note that internal Sync Gateway attachment documents, whose IDs are prefixed with _sync:att, are still processed by the specified function.)

Boolean

cursor_aware
optional

Couchbase Server 7.6.4

Specifies whether the function suppresses potential duplicate mutations caused by App Services or Sync Gateway book-keeping.

Enabling this setting guarantees that the Eventing function will only trigger once for any given mutation received from App Services or Sync Gateway.

Note that enabling this setting may have a noticeable impact on the performance of the Eventing function.

Boolean

high_seq_check_interval
optional

number of milliseconds before checking for high seq number

Integer

max_unacked_bytes
optional

max MBs to wait to send more bytes to c++ side

Integer

max_unacked_count
optional

max number of messages on c++ side

Integer

message_flush_time
optional

number of milliseconds before sending message to c++ side

Integer

max_parallel_vb
optional

number of parallel vb request per cpp thread

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

cursor_limit
optional

Couchbase Server 7.6.4

The maximum number of cursor-aware Eventing functions that can coexist on a given source keyspace. (A cursor-aware Eventing function is one for which the cursor_aware setting is true.)

Increasing this setting enables more cursor-aware Eventing functions to register and listen to any given collection.

Decreasing this setting prevents further cursor-aware Eventing functions from being registered on any given collection; however, it doesn't unregister already registered cursor-aware Eventing functions.

Default: 5
Minimum: 1
Maximum: 20

Integer

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.