The Functions service allows you to create custom behaviour that can be triggered by any supported Appwrite system events or by a predefined schedule.
Appwrite Cloud Functions lets you automatically run backend code in response to events triggered by Appwrite or by setting it to be executed in a predefined schedule. Your code is stored in a secure way on your Appwrite instance and is executed in an isolated environment.
You can learn more by following our Cloud Functions tutorial.
https://cloud.appwrite.io/v1
List functions
Get a list of all the project's functions. You can use the query params to filter your results.
Request
queries Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, enabled, runtime, deployment, schedule, scheduleNext, schedulePrevious, timeout, entrypoint, commands, installationId
search Search term to filter your list results. Max length: 256 chars.
Response
200
GET /functions
query {
functionsList(
queries: [],
search: "<SEARCH>"
) {
total
functions {
_id
_createdAt
_updatedAt
execute
name
enabled
live
logging
runtime
deployment
vars {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
events
schedule
timeout
entrypoint
commands
version
installationId
providerRepositoryId
providerBranch
providerRootDirectory
providerSilentMode
}
}
}
Create function
Create a new function. You can pass a list of permissions to allow different project users or team with access to execute the function using the client API.
Request
functionId requiredFunction ID. Choose a custom ID or generate a random ID with
ID.unique()
. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.name requiredFunction name. Max length: 128 chars.
runtime requiredExecution runtime.
execute An array of role strings with execution permissions. By default no user is granted with any execute permissions. learn more about roles. Maximum of 100 roles are allowed, each 64 characters long.
events Events list. Maximum of 100 events are allowed.
schedule Schedule CRON syntax.
timeout Function maximum execution time in seconds.
enabled Is function enabled? When set to 'disabled', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled.
logging Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project.
entrypoint Entrypoint File. This path is relative to the "providerRootDirectory".
commands Build Commands.
installationId Appwrite Installation ID for VCS (Version Control System) deployment.
providerRepositoryId Repository ID of the repo linked to the function.
providerBranch Production branch for the repo linked to the function.
providerSilentMode Is the VCS (Version Control System) connection in silent mode for the repo linked to the function? In silent mode, comments will not be made on commits and pull requests.
providerRootDirectory Path to function code in the linked repo.
templateRepository Repository name of the template.
templateOwner The name of the owner of the template.
templateRootDirectory Path to function code in the template repo.
templateBranch Production branch for the repo linked to the function template.
Response
201
POST /functions
mutation {
functionsCreate(
functionId: "<FUNCTION_ID>",
name: "<NAME>",
runtime: "node-14.5",
execute: ["any"],
events: [],
schedule: "",
timeout: 1,
enabled: false,
logging: false,
entrypoint: "<ENTRYPOINT>",
commands: "<COMMANDS>",
installationId: "<INSTALLATION_ID>",
providerRepositoryId: "<PROVIDER_REPOSITORY_ID>",
providerBranch: "<PROVIDER_BRANCH>",
providerSilentMode: false,
providerRootDirectory: "<PROVIDER_ROOT_DIRECTORY>",
templateRepository: "<TEMPLATE_REPOSITORY>",
templateOwner: "<TEMPLATE_OWNER>",
templateRootDirectory: "<TEMPLATE_ROOT_DIRECTORY>",
templateBranch: "<TEMPLATE_BRANCH>"
) {
_id
_createdAt
_updatedAt
execute
name
enabled
live
logging
runtime
deployment
vars {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
events
schedule
timeout
entrypoint
commands
version
installationId
providerRepositoryId
providerBranch
providerRootDirectory
providerSilentMode
}
}
GET /functions/runtimes
query {
functionsListRuntimes {
total
runtimes {
_id
name
version
base
image
logo
supports
}
}
}
GET /functions/{functionId}
query {
functionsGet(
functionId: "<FUNCTION_ID>"
) {
_id
_createdAt
_updatedAt
execute
name
enabled
live
logging
runtime
deployment
vars {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
events
schedule
timeout
entrypoint
commands
version
installationId
providerRepositoryId
providerBranch
providerRootDirectory
providerSilentMode
}
}
Update function
Update function by its unique ID.
Request
functionId requiredFunction ID.
name requiredFunction name. Max length: 128 chars.
runtime Execution runtime.
execute An array of role strings with execution permissions. By default no user is granted with any execute permissions. learn more about roles. Maximum of 100 roles are allowed, each 64 characters long.
events Events list. Maximum of 100 events are allowed.
schedule Schedule CRON syntax.
timeout Maximum execution time in seconds.
enabled Is function enabled? When set to 'disabled', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled.
logging Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project.
entrypoint Entrypoint File. This path is relative to the "providerRootDirectory".
commands Build Commands.
installationId Appwrite Installation ID for VCS (Version Controle System) deployment.
providerRepositoryId Repository ID of the repo linked to the function
providerBranch Production branch for the repo linked to the function
providerSilentMode Is the VCS (Version Control System) connection in silent mode for the repo linked to the function? In silent mode, comments will not be made on commits and pull requests.
providerRootDirectory Path to function code in the linked repo.
Response
200
PUT /functions/{functionId}
mutation {
functionsUpdate(
functionId: "<FUNCTION_ID>",
name: "<NAME>",
runtime: "node-14.5",
execute: ["any"],
events: [],
schedule: "",
timeout: 1,
enabled: false,
logging: false,
entrypoint: "<ENTRYPOINT>",
commands: "<COMMANDS>",
installationId: "<INSTALLATION_ID>",
providerRepositoryId: "<PROVIDER_REPOSITORY_ID>",
providerBranch: "<PROVIDER_BRANCH>",
providerSilentMode: false,
providerRootDirectory: "<PROVIDER_ROOT_DIRECTORY>"
) {
_id
_createdAt
_updatedAt
execute
name
enabled
live
logging
runtime
deployment
vars {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
events
schedule
timeout
entrypoint
commands
version
installationId
providerRepositoryId
providerBranch
providerRootDirectory
providerSilentMode
}
}
Delete function
Delete a function by its unique ID.
Request
functionId requiredFunction ID.
Response
204
DELETE /functions/{functionId}
mutation {
functionsDelete(
functionId: "<FUNCTION_ID>"
) {
status
}
}
List deployments
Get a list of all the project's code deployments. You can use the query params to filter your results.
Request
functionId requiredFunction ID.
queries Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: size, buildId, activate, entrypoint, commands
search Search term to filter your list results. Max length: 256 chars.
Response
200
GET /functions/{functionId}/deployments
query {
functionsListDeployments(
functionId: "<FUNCTION_ID>",
queries: [],
search: "<SEARCH>"
) {
total
deployments {
_id
_createdAt
_updatedAt
type
resourceId
resourceType
entrypoint
size
buildId
activate
status
buildLogs
buildTime
providerRepositoryName
providerRepositoryOwner
providerRepositoryUrl
providerBranch
providerCommitHash
providerCommitAuthorUrl
providerCommitAuthor
providerCommitMessage
providerCommitUrl
providerBranchUrl
}
}
}
Create deployment
Create a new function code deployment. Use this endpoint to upload a new version of your code function. To execute your newly uploaded code, you'll need to update the function's deployment to use your new deployment UID.
This endpoint accepts a tar.gz file compressed with your code. Make sure to include any dependencies your code has within the compressed file. You can learn more about code packaging in the Appwrite Cloud Functions tutorial.
Use the "command" param to set the entrypoint used to execute your code.
Request
functionId requiredFunction ID.
code requiredGzip file with your code package. When used with the Appwrite CLI, pass the path to your code directory, and the CLI will automatically package your code. Use a path that is within the current directory.
activate requiredAutomatically activate the deployment when it is finished building.
entrypoint Entrypoint File.
commands Build Commands.
Response
202
POST /functions/{functionId}/deployments
POST /v1/functions/{functionId}/deployments HTTP/1.1
Host: cloud.appwrite.io
Content-Type: multipart/form-data; boundary="cec8e8123c05ba25"
X-Appwrite-Response-Format: 1.5.0
X-Appwrite-Project: 5df5acd0d48c2
X-Appwrite-Key: 919c2d18fb5d4...a2ae413da83346ad2
Content-Length: *Length of your entity body in bytes*
--cec8e8123c05ba25
Content-Disposition: form-data; name="operations"
{ "query": "mutation { functionsCreateDeployment(functionId: $functionId, code: $code, activate: $activate, entrypoint: $entrypoint, commands: $commands) { id }" }, "variables": { "functionId": "<FUNCTION_ID>", "code": null, "activate": false, "entrypoint": "<ENTRYPOINT>", "commands": "<COMMANDS>" } }
--cec8e8123c05ba25
Content-Disposition: form-data; name="map"
{ "0": ["variables.code"], }
--cec8e8123c05ba25
Content-Disposition: form-data; name="0"; filename="code.ext"
File contents
--cec8e8123c05ba25--
Get deployment
Get a code deployment by its unique ID.
Request
functionId requiredFunction ID.
deploymentId requiredDeployment ID.
Response
200
GET /functions/{functionId}/deployments/{deploymentId}
query {
functionsGetDeployment(
functionId: "<FUNCTION_ID>",
deploymentId: "<DEPLOYMENT_ID>"
) {
_id
_createdAt
_updatedAt
type
resourceId
resourceType
entrypoint
size
buildId
activate
status
buildLogs
buildTime
providerRepositoryName
providerRepositoryOwner
providerRepositoryUrl
providerBranch
providerCommitHash
providerCommitAuthorUrl
providerCommitAuthor
providerCommitMessage
providerCommitUrl
providerBranchUrl
}
}
Update deployment
Update the function code deployment ID using the unique function ID. Use this endpoint to switch the code deployment that should be executed by the execution endpoint.
Request
functionId requiredFunction ID.
deploymentId requiredDeployment ID.
Response
200
PATCH /functions/{functionId}/deployments/{deploymentId}
mutation {
functionsUpdateDeployment(
functionId: "<FUNCTION_ID>",
deploymentId: "<DEPLOYMENT_ID>"
) {
_id
_createdAt
_updatedAt
execute
name
enabled
live
logging
runtime
deployment
vars {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
events
schedule
timeout
entrypoint
commands
version
installationId
providerRepositoryId
providerBranch
providerRootDirectory
providerSilentMode
}
}
Delete deployment
Delete a code deployment by its unique ID.
Request
functionId requiredFunction ID.
deploymentId requiredDeployment ID.
Response
204
DELETE /functions/{functionId}/deployments/{deploymentId}
mutation {
functionsDeleteDeployment(
functionId: "<FUNCTION_ID>",
deploymentId: "<DEPLOYMENT_ID>"
) {
status
}
}
Create build
Create a new build for an Appwrite Function deployment. This endpoint can be used to retry a failed build.
Request
functionId requiredFunction ID.
deploymentId requiredDeployment ID.
buildId requiredBuild unique ID.
Response
204
POST /functions/{functionId}/deployments/{deploymentId}/builds/{buildId}
mutation {
functionsCreateBuild(
functionId: "<FUNCTION_ID>",
deploymentId: "<DEPLOYMENT_ID>",
buildId: "<BUILD_ID>"
) {
status
}
}
Download deployment
Get a Deployment's contents by its unique ID. This endpoint supports range requests for partial or streaming file download.
Request
functionId requiredFunction ID.
deploymentId requiredDeployment ID.
Response
200
GET /functions/{functionId}/deployments/{deploymentId}/download
query {
functionsDownloadDeployment(
functionId: "<FUNCTION_ID>",
deploymentId: "<DEPLOYMENT_ID>"
) {
status
}
}
List executions
Get a list of all the current user function execution logs. You can use the query params to filter your results.
Request
functionId requiredFunction ID.
queries Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: trigger, status, responseStatusCode, duration
search Search term to filter your list results. Max length: 256 chars.
Response
200
GET /functions/{functionId}/executions
query {
functionsListExecutions(
functionId: "<FUNCTION_ID>",
queries: [],
search: "<SEARCH>"
) {
total
executions {
_id
_createdAt
_updatedAt
_permissions
functionId
trigger
status
requestMethod
requestPath
requestHeaders {
name
value
}
responseStatusCode
responseBody
responseHeaders {
name
value
}
logs
errors
duration
}
}
}
Create execution
Trigger a function execution. The returned object will return you the current execution status. You can ping the Get Execution
endpoint to get updates on the current execution status. Once this endpoint is called, your function execution process will start asynchronously.
Request
functionId requiredFunction ID.
body HTTP body of execution. Default value is empty string.
async Execute code in the background. Default value is false.
path HTTP path of execution. Path can include query params. Default value is /
method HTTP method of execution. Default value is GET.
headers HTTP headers of execution. Defaults to empty.
Response
201
POST /functions/{functionId}/executions
mutation {
functionsCreateExecution(
functionId: "<FUNCTION_ID>",
body: "<BODY>",
async: false,
path: "<PATH>",
method: "GET",
headers: "{}"
) {
_id
_createdAt
_updatedAt
_permissions
functionId
trigger
status
requestMethod
requestPath
requestHeaders {
name
value
}
responseStatusCode
responseBody
responseHeaders {
name
value
}
logs
errors
duration
}
}
Get execution
Get a function execution log by its unique ID.
Request
functionId requiredFunction ID.
executionId requiredExecution ID.
Response
200
GET /functions/{functionId}/executions/{executionId}
query {
functionsGetExecution(
functionId: "<FUNCTION_ID>",
executionId: "<EXECUTION_ID>"
) {
_id
_createdAt
_updatedAt
_permissions
functionId
trigger
status
requestMethod
requestPath
requestHeaders {
name
value
}
responseStatusCode
responseBody
responseHeaders {
name
value
}
logs
errors
duration
}
}
List variables
Get a list of all variables of a specific function.
Request
functionId requiredFunction unique ID.
Response
200
GET /functions/{functionId}/variables
query {
functionsListVariables(
functionId: "<FUNCTION_ID>"
) {
total
variables {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
}
}
Create variable
Create a new function environment variable. These variables can be accessed in the function at runtime as environment variables.
Request
functionId requiredFunction unique ID.
key requiredVariable key. Max length: 255 chars.
value requiredVariable value. Max length: 8192 chars.
Response
201
POST /functions/{functionId}/variables
mutation {
functionsCreateVariable(
functionId: "<FUNCTION_ID>",
key: "<KEY>",
value: "<VALUE>"
) {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
}
Get variable
Get a variable by its unique ID.
Request
functionId requiredFunction unique ID.
variableId requiredVariable unique ID.
Response
200
GET /functions/{functionId}/variables/{variableId}
query {
functionsGetVariable(
functionId: "<FUNCTION_ID>",
variableId: "<VARIABLE_ID>"
) {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
}
Update variable
Update variable by its unique ID.
Request
functionId requiredFunction unique ID.
variableId requiredVariable unique ID.
key requiredVariable key. Max length: 255 chars.
value Variable value. Max length: 8192 chars.
Response
200
PUT /functions/{functionId}/variables/{variableId}
mutation {
functionsUpdateVariable(
functionId: "<FUNCTION_ID>",
variableId: "<VARIABLE_ID>",
key: "<KEY>",
value: "<VALUE>"
) {
_id
_createdAt
_updatedAt
key
value
resourceType
resourceId
}
}
Delete variable
Delete a variable by its unique ID.
Request
functionId requiredFunction unique ID.
variableId requiredVariable unique ID.
Response
204
DELETE /functions/{functionId}/variables/{variableId}
mutation {
functionsDeleteVariable(
functionId: "<FUNCTION_ID>",
variableId: "<VARIABLE_ID>"
) {
status
}
}