Functions API
Full lifecycle interfaces for functions: create functions in multiple languages, code/template/VCS deployments, build and run status, synchronous/asynchronous/scheduled execution, execution records, function variables, run specifications, and replicas. The corresponding interfaces for Sites are isomorphic, see sites.
Service and resource boundaries
The Functions API (/v1/functions/*) provides management and execution interfaces for the project-level Serverless computing engine: it supports multi-language runtimes (Node.js / Python / Go / Java / PHP / Dart / .NET, etc.), multiple code sources (multipart/form-data archive upload, template cloning, Git VCS repository branch integration), multiple container specifications and warm keep-alive replicas (Warm Runtime), function-specific environment variables, event triggering and Cron scheduling, as well as synchronous/asynchronous function execution and aggregated retrieval by path (execution-paths).
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/functions.Resources:
function({functionId}),deployment(deployment package,{deploymentId}),execution(execution record,{executionId}),variable({variableId}).Top-level enumeration endpoints:
/functions/runtimes(available runtimes),/functions/specifications(build/run specifications),/functions/execution-plans(execution plans).
Authentication and Permissions
See general conventions for authentication and request header conventions. Scopes in this domain: functions.read / functions.write (functions, deployments, variables, specifications), execution.read / execution.write (executions and execution records), public (runtime list).
Security note: the API Key automatically generated for each execution does not accept passing via query string—project credentials in the execution context can only be injected via request headers; the function's scopes array determines the capability ceiling of that execution-level Key.
Endpoint overview
The Functions module provides 30 endpoints in total, divided into: function CRUD and active deployment switching (6), deployment package build and lifecycle management (9), function synchronous/asynchronous triggering and execution record/request path retrieval (6), runtime replica status and function variable management (6), and enumeration of globally available runtimes/specifications/execution plans (3).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /functions | List functions |
POST /functions | Create a function |
GET /functions/{functionId} | Get a function |
PUT /functions/{functionId} | Update function configuration |
DELETE /functions/{functionId} | Delete a function |
PATCH /functions/{functionId}/deployment | Switch the active deployment |
GET /functions/{functionId}/deployments | List deployments |
POST /functions/{functionId}/deployments | Create a deployment by uploading code |
POST /functions/{functionId}/deployments/duplicate | Duplicate an existing deployment |
POST /functions/{functionId}/deployments/template | Create a deployment from a template |
POST /functions/{functionId}/deployments/vcs | Create a deployment from a VCS branch/commit |
GET /functions/{functionId}/deployments/{deploymentId} | Get a deployment |
GET /functions/{functionId}/deployments/{deploymentId}/download | Download the deployment artifact |
PATCH /functions/{functionId}/deployments/{deploymentId}/status | Manually mark deployment status |
DELETE /functions/{functionId}/deployments/{deploymentId} | Delete a deployment |
POST /functions/{functionId}/executions | Execute a function |
GET /functions/{functionId}/executions | List execution records |
GET /functions/{functionId}/executions/{executionId} | Get an execution record |
GET /functions/{functionId}/execution-paths | Paginated list of deduplicated request paths (from 2.10.0 onwards, +path / pathMatch / method filters) |
GET /functions/{functionId}/execution-paths/executions | Query execution records by path (path required; from 2.10.0 onwards, +pathMatch / method) |
DELETE /functions/{functionId}/executions/{executionId} | Delete an execution record |
GET /functions/{functionId}/runtime-status | Runtime status (replicas/keep-alive) |
GET /functions/{functionId}/variables | List function variables |
POST /functions/{functionId}/variables | Create a variable |
GET /functions/{functionId}/variables/{variableId} | Get a variable |
PUT /functions/{functionId}/variables/{variableId} | Update a variable |
DELETE /functions/{functionId}/variables/{variableId} | Delete a variable |
GET /functions/runtimes | List available runtimes (public) |
GET /functions/specifications | List build/run specifications |
GET /functions/execution-plans | List execution plans |
Endpoint details
Synchronous and asynchronous execution (
asyncparameter): when callingPOST /v1/functions/{functionId}/executions,async=false(default) blocks and waits for the function to return the completeresponseBody,responseStatusCode, andlogs;async=trueimmediately returns aexecutionobject containing202 Acceptedandstatus: "waiting", with execution scheduled by the background queue.Dynamic injection of execution-level temporary keys: on each execution, the platform dynamically issues short-lived
APPWRITE_FUNCTION_API_KEYaccording to the function's configuredscopesarray and injects them into the container environment; the function accesses current project resources via request headers.
Requests and Responses
The following sections give the input/output specifications, copyable curl call examples, and response examples for each endpoint. Path prefix /v1; the request headers X-Appwrite-Project: <YOUR_PROJECT_ID> and X-Appwrite-Key: <YOUR_API_KEY> are consistent across all endpoints and are not explained individually in the examples.
Function CRUD
GET /v1/functions
Lists all functions in the project with pagination, supporting filtering by attributes such as name, runtime, and enabled status, and keyword search (scope functions.read. SDK: Functions.list.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Array of query strings, generated by the SDK's Query constructor (e.g. limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: name, enabled, runtime, deploymentId, schedule, scheduleNext, schedulePrevious, timeout, entrypoint, commands, installationId. Maximum of 100 items, each up to 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model functionList: total (total number of matches, not calculated when total=false) + functions[] (current page of data).
Key fields of the element model function:
| Field | Type | Description |
|---|---|---|
$id | string | Function ID. |
$createdAt | string | Function creation time (ISO 8601). |
$updatedAt | string | Function update time (ISO 8601). |
execute | string[] | Array of roles that can execute this function. |
name | string | Function name. |
enabled | boolean | Whether the function is enabled. |
live | boolean | Whether the function is deployed with the latest configuration. Becomes false after modifying configuration that requires redeployment (variables/entry point/build command, etc.), and returns to true after redeployment. |
logging | boolean | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
runtime | string | Runtime used for function build and execution. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
scopes | string[] | List of scopes allowed for execution-level auto-generated API Keys. |
events | string[] | List of trigger events. |
schedule | string | CRON-format scheduled expression. |
timeout | integer | Maximum execution time (seconds). |
Call example:
curl -G "https://<your-endpoint>/v1/functions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=hello"Response example:
{
"total": 5,
"functions": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}
]
}POST /v1/functions
Create a function: define the runtime, entry point and build command, trigger events, CRON schedule, build/runtime specs, and scopes of the execution-level API Key (scope functions.write. SDK: Functions.create.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | body | string | Yes | — | Function ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. Up to 36 characters. |
name | body | string | Yes | — | Function name. Up to 128 characters. |
runtime | body | string | Yes | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 …… (see GET /functions/runtimes for the full list) | Execution runtime. |
execute | body | string[] | No | — | Array of role strings with execution permission. By default no roles are granted. Maximum of 100 roles, each up to 64 characters. |
events | body | string[] | No | — | List of trigger events. Maximum of 100. |
schedule | body | string | No | — | CRON-format scheduled expression. |
timeout | body | integer | No | — | Maximum execution time (seconds). |
enabled | body | boolean | No | — | Whether to enable the function. When disabled, it is inaccessible from the user side, but a Server SDK holding an API Key can still access it; toggling does not lose data. |
logging | body | boolean | No | — | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
entrypoint | body | string | No | — | Entry file. Path is relative to providerRootDirectory. |
commands | body | string | No | — | Build command. |
scopes | body | string[] | No | — | List of scopes allowed for the API Key auto-generated per execution. Maximum of 100. |
installationId | body | string | No | — | AppBase installation ID used for VCS deployment. |
providerRepositoryId | body | string | No | — | VCS repository ID associated with the function. |
providerBranch | body | string | No | — | Production branch of the repository associated with the function. |
providerSilentMode | body | boolean | No | — | Whether the VCS connection of the repository associated with the function is in silent mode. In silent mode, no comments are posted on commits and PRs. |
providerRootDirectory | body | string | No | — | Path of the function code in the associated repository. |
buildSpecification | body | string | No | — | Build spec is fixed to the platform function build tier. |
runtimeSpecification | body | string | No | — | Runtime spec used for function execution. |
runtimeReplicas | body | integer | No | — | Number of reusable resident runtime replicas for function execution. Allowed values: 1 / 2 / 3 / 5 / 10. |
runtimeKeepAliveMode | body | string | No | disabled / always / schedule | Runtime keep-alive mode: disabled / always / schedule. |
runtimeKeepAliveStart | body | string | No | May be null | Daily keep-alive window start time (HH:mm). Required in schedule mode. |
runtimeKeepAliveEnd | body | string | No | May be null | Daily keep-alive window end time (HH:mm). Required in schedule mode. |
runtimeKeepAliveTimezone | body | string | No | africa/abidjan / africa/accra / africa/addis_ababa / africa/algiers / africa/asmara / africa/bamako / africa/bangui / africa/banjul …… (420 in total) | IANA time zone name used to evaluate the keep-alive window. |
buildExecutionPlan | body | string | No | May be null | Execution plan used for function deployment builds. Omit to use legacy defaults. |
runtimeExecutionPlan | body | string | No | May be null | Execution plan used for function execution. Omit to use legacy defaults. |
deploymentRetention | body | integer | No | — | Number of retention days before non-active deployments are deleted. 0 means retain all. |
Output: 201, model function, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Function ID. |
$createdAt | string | Function creation time (ISO 8601). |
$updatedAt | string | Function update time (ISO 8601). |
execute | string[] | Array of roles that can execute this function. |
name | string | Function name. |
enabled | boolean | Whether the function is enabled. |
live | boolean | Whether the function is deployed with the latest configuration. Becomes false after modifying configuration that requires redeployment (variables/entry point/build command, etc.), and returns to true after redeployment. |
logging | boolean | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
runtime | string | Runtime used for function build and execution. |
deploymentRetention | integer | Retention days for non-active deployments; they are automatically deleted upon expiry. |
deploymentId | string | ID of the currently active deployment. |
deploymentCreatedAt | string | Creation time of the active deployment (ISO 8601). |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentCreatedAt | string | Creation time of the latest deployment (ISO 8601). |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
scopes | string[] | List of scopes allowed for execution-level auto-generated API Keys. |
vars | variable[] | List of function variables. |
events | string[] | List of trigger events. |
schedule | string | CRON-format scheduled expression. |
timeout | integer | Maximum execution time (seconds). |
entrypoint | string | Entry file of the deployed code. |
commands | string | Build command of the deployment. |
version | string | Open Runtimes version used by the function. |
installationId | string | VCS (version control system) installation ID associated with the function. |
providerRepositoryId | string | VCS (version control system) repository ID. |
providerBranch | string | VCS (version control system) branch name. |
providerRootDirectory | string | Path of the function code in the VCS repository. |
providerSilentMode | boolean | Whether the VCS connection is in silent mode. In silent mode, no comments are posted on the repository's PRs / MRs. |
buildSpecification | string | Fixed machine spec used for builds (CPU/memory tier). |
runtimeSpecification | string | Machine spec used for execution (CPU/memory tier). |
runtimeReplicas | integer | Number of reusable resident runtime replicas for function execution. |
runtimeKeepAliveMode | string | Runtime keep-alive mode: disabled / always / schedule. |
runtimeKeepAliveStart | string | Daily keep-alive window start time (HH:mm). |
runtimeKeepAliveEnd | string | Daily keep-alive window end time (HH:mm). |
runtimeKeepAliveTimezone | string | IANA time zone name used to evaluate the keep-alive window. |
buildExecutionPlan | string | Execution plan used for deployment builds. |
runtimeExecutionPlan | string | Execution plan used for function execution. |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"functionId": "hello-world",
"name": "My Function",
"runtime": "node-22",
"execute": [
"users"
],
"events": [
"users.*.create"
],
"schedule": "0 8 * * *",
"timeout": 15,
"scopes": [
"databases.read",
"documents.read",
"users.read"
],
"entrypoint": "src/main.js",
"commands": "npm install"
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}GET /v1/functions/{functionId}
Read the full configuration of a single function by ID, including active/latest deployment pointers and the live flag (scope functions.read. SDK: Functions.get.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
Output: 200, model function (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Function ID. |
$createdAt | string | Function creation time (ISO 8601). |
$updatedAt | string | Function update time (ISO 8601). |
execute | string[] | Array of roles that can execute this function. |
name | string | Function name. |
enabled | boolean | Whether the function is enabled. |
live | boolean | Whether the function is deployed with the latest configuration. Becomes false after modifying configuration that requires redeployment (variables/entry point/build command, etc.), and returns to true after redeployment. |
logging | boolean | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
runtime | string | Runtime used for function build and execution. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
scopes | string[] | List of scopes allowed for execution-level auto-generated API Keys. |
events | string[] | List of trigger events. |
schedule | string | CRON-format scheduled expression. |
timeout | integer | Maximum execution time (seconds). |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}PUT /v1/functions/{functionId}
Update function configuration (scope functions.write; SDK: Functions.update). Some omitted fields are written using API defaults; for example, execute, events, and scopes may be cleared. Read the current configuration first (scope functions.read) and explicitly submit the settings that must be retained. See the table for fields such as execution plans that have different omission behavior. Configuration changes may require redeployment.
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | Yes | — | Function name. Up to 128 characters. |
runtime | body | string | No | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 …… (full list subject to GET /functions/runtimes);Omission preserves current value | execution runtime. |
execute | body | string[] | No | [] | Array of role strings with execution permission. By default no roles are granted. Maximum of 100 roles, each up to 64 characters. |
events | body | string[] | No | [] | List of trigger events. Maximum of 100. |
schedule | body | string | No | Omission preserves current value | CRON expression. A non-empty update requires exactly one existing compact execution schedule; a missing rule errors and multiple rules conflict. |
timeout | body | integer | No | 15 | Maximum execution time (seconds). |
enabled | body | boolean | No | true | Whether to enable the function. When disabled, it is inaccessible from the user side, but a Server SDK holding an API Key can still access it; toggling does not lose data. |
logging | body | boolean | No | true | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
entrypoint | body | string | No | Empty value retains current entrypoint | Entry file. Path is relative to providerRootDirectory. |
commands | body | string | No | "" | Build command. |
scopes | body | string[] | No | [] | List of scopes allowed for the API Key auto-generated per execution. Maximum of 100. |
installationId | body | string | No | "" | AppBase installation ID used for VCS deployment. |
providerRepositoryId | body | string | No | null | ID of the VCS repository associated with the function. |
providerBranch | body | string | No | "" | Production branch of the repository associated with the function. |
providerSilentMode | body | boolean | No | false | Whether the VCS connection of the repository associated with the function is in silent mode. In silent mode, no comments are posted on commits and PRs. |
providerRootDirectory | body | string | No | "" | Path of the function code in the associated repository. |
buildSpecification | body | string | No | Platform-fixed build specification | Build spec is fixed to the platform function build tier. |
runtimeSpecification | body | string | No | Omission preserves current value | Runtime spec used for function execution. |
runtimeReplicas | body | integer | No | Omission preserves current value | Number of reusable resident runtime replicas for function execution. Allowed values: 1 / 2 / 3 / 5 / 10. |
runtimeKeepAliveMode | body | string | No | disabled / always / schedule;Omission preserves current value | Runtime keep-alive mode: disabled / always / schedule. Omit to keep the current value. |
runtimeKeepAliveStart | body | string | No | Omission uses current value; non-schedule mode normalizes it to null | Daily keep-alive window start time (HH:mm). Required in schedule mode. |
runtimeKeepAliveEnd | body | string | No | Omission uses current value; non-schedule mode normalizes it to null | Daily keep-alive window end time (HH:mm). Required in schedule mode. |
runtimeKeepAliveTimezone | body | string | No | Omission preserves current value | IANA time zone name used to evaluate the keep-alive window. Omit to keep the current value. |
buildExecutionPlan | body | string | No | Omission preserves current value | Execution plan used for the function deployment build. Omit to keep the current value. |
runtimeExecutionPlan | body | string | No | Omission preserves current value | Execution plan used for function execution. Omit to keep the current value. |
deploymentRetention | body | integer | No | 0 | Number of retention days before non-active deployments are deleted. 0 means retain all. |
functionId | path | string | Yes | — | Function ID. |
Output: 200, model function (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Function ID. |
$createdAt | string | Function creation time (ISO 8601). |
$updatedAt | string | Function update time (ISO 8601). |
execute | string[] | Array of roles that can execute this function. |
name | string | Function name. |
enabled | boolean | Whether the function is enabled. |
live | boolean | Whether the function is deployed with the latest configuration. Becomes false after modifying configuration that requires redeployment (variables/entry point/build command, etc.), and returns to true after redeployment. |
logging | boolean | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
runtime | string | Runtime used for function build and execution. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
scopes | string[] | List of scopes allowed for execution-level auto-generated API Keys. |
events | string[] | List of trigger events. |
schedule | string | CRON-format scheduled expression. |
timeout | integer | Maximum execution time (seconds). |
Request guidance: Read the current configuration and check the update defaults before submitting the settings that must be retained. Do not send a partial update request without reviewing those defaults.
Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}DELETE /v1/functions/{functionId}
Delete a function by ID (scope functions.write. SDK: Functions.delete.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
_Binary stream or no response body (see output description)._
PATCH /v1/functions/{functionId}/deployment
Switch the function's active deployment: from now on, all access and execution of this function use the code of the newly activated deployment (scope functions.write. SDK: Functions.updateFunctionDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
deploymentId | body | string | Yes | — | Deployment ID. |
functionId | path | string | Yes | — | Function ID. |
Output: 200, model function (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Function ID. |
$createdAt | string | Function creation time (ISO 8601). |
$updatedAt | string | Function update time (ISO 8601). |
execute | string[] | Array of roles that can execute this function. |
name | string | Function name. |
enabled | boolean | Whether the function is enabled. |
live | boolean | Whether the function is deployed with the latest configuration. Becomes false after modifying configuration that requires redeployment (variables/entry point/build command, etc.), and returns to true after redeployment. |
logging | boolean | When disabled, execution records do not include logs and errors, and execution is slightly faster. |
runtime | string | Runtime used for function build and execution. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
scopes | string[] | List of scopes allowed for execution-level auto-generated API Keys. |
events | string[] | List of trigger events. |
schedule | string | CRON-format scheduled expression. |
timeout | integer | Maximum execution time (seconds). |
Call example:
curl -X PATCH "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deploymentId": "5e5ea5c16897e"
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}Deployment
GET /v1/functions/{functionId}/deployments
List all deployments of the function with pagination, for build history and status inspection (scope functions.read. SDK: Deployments.listDeployments.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
queries | query | string[] | No | Default [] | Query string array, generated by the SDK's Query builder (of the form limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: buildSize, sourceSize, totalSize, buildDuration, status, activate, type. At most 100 entries, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model deploymentList: total (total number of matches, not calculated when total=false) + deployments[] (current page of data).
Key fields of the element model deployment:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=hello"Response example:
{
"total": 5,
"deployments": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}
]
}POST /v1/functions/{functionId}/deployments
Upload a gzipped source package or a pre-built Java 17 JAR to create a new deployment (multipart/form-data); the build runs asynchronously and immediately returns 202 and the deployment record (scope functions.write; Functions SDK: createDeployment).
Input (multipart/form-data; file fields uploaded via -F "code=@./code.tgz")
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
entrypoint | body (form) | string | No | Nullable null | Entry file. |
commands | body (form) | string | No | Nullable null | Build command. |
code | body (form) | string | Yes | — | Gzipped code package (artifactMode=source) or executable JAR (artifactMode=java-jar). When using the AppBase CLI, pass the code directory path and the CLI will package it automatically; the path must be inside the current directory. |
artifactMode | body (form) | string | No | source / java-jar (default source) | Upload mode (added in 2.10.0): source means a gzip source package; java-jar means an executable Java 17 JAR (the real entry point is the Main-Class specified in the manifest; Index.java is a compatibility marker; the JAR size limit defaults to 100,000,000 bytes, and is also subject to the plan's deployment size limit). |
activate | body (form) | boolean | Yes | — | Whether to automatically activate this deployment after the build completes. |
functionId | path | string | Yes | — | Function ID. |
JAR mode requires the target Function's runtime to be java-17.0; the package must contain the entry class specified by the manifest, the application must listen on port 3000 and provide /__opr/health; the source entry and build command do not need to be filled in. During chunked upload, all chunks must use the same artifactMode. 202 only means the deployment was received; you must continue checking that the status reaches ready, that the Function's current deploymentId matches the target, and verify actual execution; activate=true is not a guarantee of successful execution.
Output: 202, model deployment, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
$updatedAt | string | Deployment update time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
screenshotLight | string | File ID of the light-theme screenshot. |
screenshotDark | string | File ID of the dark-theme screenshot. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildLogs | string | Build logs. |
buildDuration | integer | Current build duration (seconds). |
providerRepositoryName | string | VCS provider repository name. |
providerRepositoryOwner | string | VCS repository owner name. |
providerRepositoryUrl | string | VCS repository URL. |
providerCommitHash | string | VCS commit hash. |
providerCommitAuthorUrl | string | VCS commit author profile page. |
providerCommitAuthor | string | VCS commit author name. |
providerCommitMessage | string | Commit message. |
providerCommitUrl | string | VCS commit URL. |
providerBranch | string | VCS repository branch. |
providerBranchUrl | string | VCS repository branch. |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-F "entrypoint=src/main.js" \
-F "commands=npm install" \
-F "code=@./code.tgz" \
-F "activate=true"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/duplicate
Start a new build from an existing deployment: repackage according to the function's current configuration (including modified entry/build commands), without re-uploading source code (scope functions.write. SDK: Deployments.createDuplicateDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
deploymentId | body | string | Yes | — | Deployment ID. |
buildId | body | string | No | — | ID of this build. |
functionId | path | string | Yes | — | Function ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/duplicate" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deploymentId": "5e5ea5c16897e",
"buildId": "6aa2d1b8c2e8f"
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/template
Create a deployment from a template repository: specify the template's repository, owner, directory, and reference (commit/branch/tag) (scope functions.write. SDK: Deployments.createTemplateDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
repository | body | string | Yes | — | Template repository name. |
owner | body | string | Yes | — | Template repository owner. |
rootDirectory | body | string | Yes | — | Path of the function code within the template repository. |
type | body | string | Yes | commit / branch / tag | Type of the reference: commit / branch / tag. |
reference | body | string | Yes | — | Value of the reference: commit hash, branch name, or release tag. |
activate | body | boolean | No | — | Whether to automatically activate this deployment after the build completes. |
functionId | path | string | Yes | — | Function ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/template" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"repository": "agentbase/function-templates",
"owner": "agentbase",
"rootDirectory": "hello-world",
"type": "commit",
"reference": "prod",
"activate": true
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/vcs
For functions already linked to a VCS, create a deployment from a branch or commit in its repository (scope functions.write. SDK: Deployments.createVcsDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
type | body | string | Yes | branch / commit | Type of the reference: branch / commit. |
reference | body | string | Yes | — | VCS reference used to create the deployment: branch name or commit hash (depending on type). |
activate | body | boolean | No | — | Whether to automatically activate this deployment after the build completes. |
functionId | path | string | Yes | — | Function ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/vcs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"type": "commit",
"reference": "prod",
"activate": true
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}GET /v1/functions/{functionId}/deployments/{deploymentId}
Read the details of a single deployment; this is the standard entry point for polling build status (scope functions.read. SDK: Deployments.getDeployment.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 200, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}GET /v1/functions/{functionId}/deployments/{deploymentId}/download
Download the deployment's source package (type=source) or build artifact (type=output); returns an attachment binary stream (scope functions.read. SDK: Deployments.getDeploymentDownload.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
type | query | string | No | source / output; default "source" | Content to download: source (source package) or output (build artifact). |
Output: 200, binary file stream (Content-Disposition: attachment attachment download; type=source is the source package, type=output is the build artifact).
Call example:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>/download" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-o deployment.tgz \
--data-urlencode "type=source"Response example:
_Binary stream or no response body (see output description)._
PATCH /v1/functions/{functionId}/deployments/{deploymentId}/status
Cancel an in-progress or queued deployment build: in-progress builds are stopped and marked canceled; builds that are completed (ready) or failed (failed) cannot be canceled (scope functions.write. SDK: Deployments.updateDeploymentStatus.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 200, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
artifactMode | string | Upload mode: source / java-jar (added in 2.10.0). |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X PATCH "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}DELETE /v1/functions/{functionId}/deployments/{deploymentId}
Delete the specified deployment (for the active deployment, switch to another deployment before deleting) (scope functions.write. SDK: Deployments.deleteDeployment.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
_Binary stream or no response body (see output description)._
Execution
POST /v1/functions/{functionId}/executions
Trigger a function execution: synchronously wait for the result, async=true for background execution with polling records, or scheduledAt for scheduled execution (scope execution.write. SDK: Executions.createExecution.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
body | body | string | No | — | Execution request body. Defaults to an empty string. |
async | body | boolean | No | — | Whether to execute in the background. Default false. |
path | body | string | No | — | Execution path, may include query parameters. Default /. |
method | body | string | No | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | HTTP method. Defaults to POST. |
headers | body | object | No | — | Execution request headers. Empty by default. |
scheduledAt | body | string | No | Can be null | Scheduled execution time (ISO 8601). Must be a future time, with minute-level precision. |
functionId | path | string | Yes | — | Function ID. |
Output: 201, model execution, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Execution record ID. |
$createdAt | string | Execution record creation time (ISO 8601). |
$updatedAt | string | Execution record update time (ISO 8601). |
$permissions | string[] | Execution role. |
functionId | string | Function ID. |
deploymentId | string | ID of the deployment used to trigger this execution. |
trigger | string | Trigger source: http / schedule / event. |
status | string | Execution status: waiting / processing / completed / failed / scheduled. |
requestMethod | string | HTTP request method. |
requestPath | string | HTTP request path (may include the query string). |
requestHeaders | headers[] | HTTP request header key-value object. Only whitelisted headers are returned; executions created synchronously return all request headers. |
responseStatusCode | integer | HTTP response status code. |
responseBody | string | HTTP response body returned by the function. |
responseHeaders | headers[] | HTTP response header key-value object. Only whitelisted headers are returned; executions created synchronously return all response headers. |
logs | string | Function logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
errors | string | Function error output (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
duration | number | Execution duration of the resource (function/site) in seconds. |
scheduledAt | string | Scheduled execution time. If left empty, execution is queued immediately. |
Call example:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"body": "{\"now\": true}",
"async": false,
"path": "/",
"method": "POST",
"headers": {
"X-Custom-Header": "value"
}
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}GET /v1/functions/{functionId}/executions
List the execution records of this function with pagination, filterable by status, duration, and trigger time (scope execution.read. SDK: Functions.listExecutions.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
queries | query | string[] | No | Default [] | Query string array, generated by the SDK's Query builder (of the form limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: trigger, status, responseStatusCode, duration, requestMethod, requestPath, deploymentId. At most 100 entries, each at most 4096 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
path | query | string | No | Empty by default | Full request path or regex; the query string participates in matching. In the Node Server object, the parameter name is xpath. |
pathMatch | query | string | No | exact / regex, default exact | Regex must not carry /…/ delimiters; invalid expressions are rejected. |
method | query | string | No | GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS | Takes effect together with the path and queries conditions; when omitted, all methods are kept. |
Accessing the execution record list and path list via the Agentbase Web SDK returns 403 general_resource_blocked; use the Console or a controlled server-side identity to read them, and do not bypass the restriction by modifying the SDK identifier. This list restriction does not cover querying a single execution by ID.
Output: 200, model executionList: total (total number of matches, not calculated when total=false) + executions[] (current page of data).
Key fields of the element model execution:
| Field | Type | Description |
|---|---|---|
$id | string | Execution record ID. |
$createdAt | string | Execution record creation time (ISO 8601). |
functionId | string | Function ID. |
deploymentId | string | ID of the deployment used to trigger this execution. |
trigger | string | Trigger source: http / schedule / event. |
status | string | Execution status: waiting / processing / completed / failed / scheduled. |
requestMethod | string | HTTP request method. |
requestPath | string | HTTP request path (may include the query string). |
responseStatusCode | integer | HTTP response status code. |
responseBody | string | HTTP response body returned by the function. |
logs | string | Function logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
errors | string | Function error output (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
duration | number | Execution duration of the resource (function/site) in seconds. |
Call example:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"Response example:
{
"total": 5,
"executions": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}
]
}GET /v1/functions/{functionId}/executions/{executionId}
Read a single execution record: async=true or the entry point for obtaining results and logs after a scheduled execution (scope execution.read. SDK: Executions.getExecution.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
executionId | path | string | Yes | — | Execution record ID. |
Output: 200, model execution (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Execution record ID. |
$createdAt | string | Execution record creation time (ISO 8601). |
functionId | string | Function ID. |
deploymentId | string | ID of the deployment used to trigger this execution. |
trigger | string | Trigger source: http / schedule / event. |
status | string | Execution status: waiting / processing / completed / failed / scheduled. |
requestMethod | string | HTTP request method. |
requestPath | string | HTTP request path (may include the query string). |
responseStatusCode | integer | HTTP response status code. |
responseBody | string | HTTP response body returned by the function. |
logs | string | Function logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
errors | string | Function error output (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
duration | number | Execution duration of the resource (function/site) in seconds. |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions/<EXECUTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}DELETE /v1/functions/{functionId}/executions/{executionId}
Delete a single execution record (only cleans up the record; does not affect the function) (scope execution.write. SDK: Executions.deleteExecution.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
executionId | path | string | Yes | — | Execution record ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions/<EXECUTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
_Binary stream or no response body (see output description)._
GET /v1/functions/{functionId}/execution-paths
List the deduplicated request paths of existing execution records with pagination.
scope:execution.read;Server SDK:Functions.listExecutionPaths。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
limit | query | integer | No | 25 | Maximum number of records to return. |
offset | query | integer | No | 0 | Number of records to skip. |
total | query | boolean | No | true | Whether to compute the total count; when false, the returned total is 0. |
path | query | string | No | — | Filter by request path (added in 2.10.0); combine with pathMatch to choose exact or regex matching. |
pathMatch | query | string | No | exact / regex (default exact) | Path matching mode (added in 2.10.0). |
method | query | string | No | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | Filter by HTTP method (added in 2.10.0). |
output: 200, model executionPathList.
| Field | Type | Description |
|---|---|---|
total | integer | Total number of deduplicated request paths. |
paths | string[] | Deduplicated request paths on this page. |
Call example:
curl --get "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/execution-paths" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/functions/{functionId}/execution-paths/executions
Query execution records by request path with pagination.
scope:execution.read;Server SDK:Functions.listExecutionsByPath。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
path | query | string | Yes | — | Execution request path; exact match by default, regex when pathMatch=regex (since 2.10.0). |
queries | query | string[] | No | [] | Array of SDK Query strings; at most 100 items, each up to 4096 characters. |
total | query | boolean | No | true | Whether to compute the total count; when false, the returned total is 0. |
pathMatch | query | string | No | exact / regex (default exact) | Path matching mode (added in 2.10.0). |
method | query | string | No | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | Filter by HTTP method (added in 2.10.0). |
output: 200, model executionList.
Returns the executions execution record array and total; for execution record fields, see "Executions" on this page.
Call example:
curl --get "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/execution-paths/executions" \
--data-urlencode "path=/webhook" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Runtime status and enums
GET /v1/functions/{functionId}/runtime-status
Read a safe status summary of the function's resident runtime (healthy / attention / limited / maintenance / unknown) (scope functions.read. SDK: Functions.getRuntimeStatus.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
Output: 200, model runtimeStatus, fields:
| Field | Type | Description |
|---|---|---|
status | string | Runtime status summary. |
coverage | string | Coverage of the status data. |
updatedAt | string | Last update time of the underlying resource. |
message | string | User-facing safe status message. |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/runtime-status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"status": "healthy",
"coverage": "configuration-only",
"updatedAt": "2026-07-12T00:00:00.000+00:00",
"message": "All runtime replicas are healthy."
}GET /v1/functions/runtimes
List all available runtimes on the current instance (public scope; readable without authorization beyond an API Key) (scope public. SDK: Runtimes.listRuntimes.)
input: Path parameters only; no query or request body.
Output: 200, model runtimeList: total (total number of matches, not calculated when total=false) + runtimes[] (current page of data).
Key fields of the element model runtime:
| Field | Type | Description |
|---|---|---|
$id | string | Runtime ID. |
key | string | Key name of the owning runtime. |
name | string | Runtime name. |
version | string | Runtime version. |
base | string | Base Docker image used to build this runtime. |
image | string | Docker Hub image name. |
supports | string[] | List of supported CPU architectures. |
Call example:
curl "https://<your-endpoint>/v1/functions/runtimes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 5,
"runtimes": [
{
"$id": "66f1a2b3c4d5e6f7",
"key": "python",
"name": "Python",
"version": "3.8",
"base": "python:3.8-alpine",
"image": "appbase\\/runtime-for-python:3.8",
"logo": "python.png",
"supports": [
"amd64"
]
}
]
}GET /v1/functions/specifications
List the build/run machine specifications allowed by the instance (CPU and memory tiers) (scope functions.read. SDK: Runtimes.listSpecifications.)
input: Path parameters only; no query or request body.
Output: 200, model specificationList: total (total number of matches, not calculated when total=false) + specifications[] (current page of data).
Key fields of the element model specification:
| Field | Type | Description |
|---|---|---|
memory | integer | Memory size (MB). |
cpus | number | Number of CPU cores. |
enabled | boolean | Whether this specification is enabled. |
slug | string | Specification identifier (slug). |
Model specificationList additional field: defaultRuntimeSpecification (string, added in 2.10.0) — the default runtime specification slug for new functions configured by platform administrators; it is null when unavailable for the current plan or compute. This default is applied to newly created Functions when no specification is explicitly specified.
Call example:
curl "https://<your-endpoint>/v1/functions/specifications" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 5,
"specifications": [
{
"memory": 512,
"cpus": 1,
"enabled": true,
"slug": "s-1vcpu-512mb"
}
]
}GET /v1/functions/execution-plans
List the execution plans (resource tier packages) available for function build/run, filterable by runtime (scope functions.read. SDK: ExecutionPlans.listExecutionPlans.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
runtime | query | string | No | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 …… (see GET /functions/runtimes for the full list) | Function runtime used to filter execution plans. |
Output: 200, model executionPlanList: total (total number of matches, not calculated when total=false) + executionPlans[] (current page of data).
Key fields of the element model executionPlan:
| Field | Type | Description |
|---|---|---|
id | string | Stable execution plan ID. |
name | string | Execution plan display name. |
summary | string | Execution plan description. |
suitableFor | string | Resource type supported by this execution plan. |
recommended | boolean | Whether this is a recommended execution plan. |
availability | string | Availability of this execution plan. |
effectiveOn | string | Effective timing of the selected execution plan. |
Call example:
curl -G "https://<your-endpoint>/v1/functions/execution-plans" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "runtime=node-22"Response example:
{
"total": 5,
"executionPlans": [
{
"id": "legacy-default",
"name": "Default runtime",
"summary": "Use the verified shared runtime baseline.",
"suitableFor": "Supported Function and Site runtimes.",
"recommended": true,
"availability": "available",
"effectiveOn": "Next build or execution.",
"disabledReason": null
}
]
}Function variables
GET /v1/functions/{functionId}/variables
List all environment variables of this function (secret variable values are not echoed in plaintext) (scope functions.read. SDK: Variables.listVariables.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
Output: 200, model variableList: total (total number of matches, not calculated when total=false) + variables[] (current page of data).
Key fields of the element model variable:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 5,
"variables": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
]
}POST /v1/functions/{functionId}/variables
Create a function environment variable: injected into the function process as an environment variable at build and run time (scope functions.write. SDK: Variables.createVariable.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
key | body | string | Yes | — | Variable key name. Up to 255 characters. |
value | body | string | Yes | — | Variable value. Up to 8192 characters. |
secret | body | boolean | No | — | Secret variables can be updated/deleted, but only the function can read them at build and run time. |
functionId | path | string | Yes | — | Function ID. |
Output: 201, model variable, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
$createdAt | string | Variable creation time (ISO 8601). |
$updatedAt | string | Variable creation time (ISO 8601). |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "Content-Type: application/json" \
-d '{
"key": "APP_ENV",
"value": "development",
"secret": false
}'
)Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}GET /v1/functions/{functionId}/variables/{variableId}
Read a single variable by ID (secret variable values are masked) (scope functions.read. SDK: Variables.getVariable.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 200, model variable (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}PUT /v1/functions/{functionId}/variables/{variableId}
Update a variable: after modification, a redeployment (or reactivation of the deployment) is required for subsequent executions to take effect (scope functions.write. SDK: Variables.updateVariable.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
key | body | string | Yes | — | Variable key name. Up to 255 characters. |
value | body | string | No | Can be a null | variable value. Maximum 8192 characters. |
secret | body | boolean | No | Can be a null | Secret variables can be updated/deleted, but only functions can read them at build and runtime. |
functionId | path | string | Yes | — | Function ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 200, model variable (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X PUT "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "Content-Type: application/json" \
-d '{
"key": "APP_ENV",
"value": "development",
"secret": false
}'
)Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}DELETE /v1/functions/{functionId}/variables/{variableId}
Delete a specified variable (scope functions.write. SDK: Variables.deleteVariable.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
functionId | path | string | Yes | — | Function ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
_Binary stream or no response body (see output description)._
Errors and boundaries
Function/deployment/execution/variable not found:
404+function_not_found/deployment_not_found/execution_not_found/variable_not_found.Duplicate ID:
409+function_already_exists/variable_already_exists.Build failure: deployment
status=failed, build output in the deployment record'sbuildLogs;PATCH .../deployments/{deploymentId}/statuscan only cancel builds that are in progress or queued (marked ascanceled) and cannot substitute for a fix.Synchronous execution is subject to
timeout; on timeout it returns execution recordfailed; executions ofasync=trueandscheduledAthave no synchronous response body.The
runtimevalue must come fromGET /functions/runtimes;runtimeReplicasonly accepts1/2/3/5/10; in keep-aliveschedulemode, missing start/end returns a parameter error.Execution-level API keys must not be passed via query string; when passing credentials in
headers, be careful not to log them (logging=falsecan disable logging).Deployment package size limits and build duration are subject to the platform execution plan; automatic cleanup triggered by
deploymentRetentiononly deletes non-active deployments.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Functions.list / create / get / update / delete | /functions CRUD |
Functions.updateFunctionDeployment | PATCH /functions/{functionId}/deployment |
Functions.listDeployments / createDeployment / createDuplicateDeployment / createTemplateDeployment / createVcsDeployment / getDeployment / getDeploymentDownload / updateDeploymentStatus / deleteDeployment | /functions/{functionId}/deployments* |
Functions.createExecution / listExecutions / getExecution / deleteExecution | /functions/{functionId}/executions* |
Functions.listExecutionPaths / listExecutionsByPath | /functions/{functionId}/execution-paths* |
Functions.getRuntimeStatus | GET /functions/{functionId}/runtime-status |
Functions.listVariables / createVariable / getVariable / updateVariable / deleteVariable | /functions/{functionId}/variables* |
Functions.listRuntimes | GET /functions/runtimes |
Functions.listSpecifications | GET /functions/specifications |
Functions.listExecutionPlans | GET /functions/execution-plans |
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
POST /functions | functions.write | functions.create |
PUT /functions/{functionId} | functions.write | functions.update |
GET /projects/{projectId}/schedules | schedules.read | projects.listSchedules |
POST /projects/{projectId}/schedules | schedules.write | projects.createSchedule |
GET /projects/{projectId}/schedules/{scheduleId} | schedules.read | projects.getSchedule |
PATCH /projects/{projectId}/schedules/{scheduleId} | schedules.write | projects.updateSchedule |
DELETE /projects/{projectId}/schedules/{scheduleId} | schedules.write | projects.deleteSchedule |
POST /functions
Create function
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
functionId | body | yes | string | — | Function 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 | body | yes | string | — | Function name. Max length: 128 chars. |
runtime | body | yes | string | enum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 … | Execution runtime. |
execute | body | no | array[string] | default=[] | 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 | body | no | array[string] | default=[] | Events list. Maximum of 100 events are allowed. |
schedule | body | no | string | default="" | Schedule CRON syntax. |
timeout | body | no | integer | format=int32; default=15 | Function maximum execution time in seconds. |
enabled | body | no | boolean | default=true | 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 | body | no | boolean | default=true | When disabled, executions will exclude logs and errors, and will be slightly faster. |
entrypoint | body | no | string | default="" | Entrypoint File. This path is relative to the "providerRootDirectory". |
commands | body | no | string | default="" | Build Commands. |
scopes | body | no | array[string] | default=[] | List of scopes allowed for API key auto-generated for every execution. Maximum of 100 scopes are allowed. |
installationId | body | no | string | default="" | Agentbase Installation ID for VCS (Version Control System) deployment. |
providerRepositoryId | body | no | string | default="" | Repository ID of the repo linked to the function. |
providerBranch | body | no | string | default="" | Production branch for the repo linked to the function. |
providerSilentMode | body | no | boolean | default=false | 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 | body | no | string | default="" | Path to function code in the linked repo. |
buildSpecification | body | no | string | default="s-1vcpu-2gb" | Build specification is fixed to the platform Function build profile. |
runtimeSpecification | body | no | string | default={} | Runtime specification for the function executions. |
runtimeReplicas | body | no | integer | format=int32; default=1 | Number of reusable runtime replicas for function executions. Allowed values are 1, 2, 3, 5, and 10. |
runtimeKeepAliveMode | body | no | string | enum=disabled, always, schedule; default="disabled" | Runtime keep-alive mode. Allowed values are disabled, always, and schedule. |
runtimeKeepAliveStart | body | no | string | — | Daily runtime keep-alive window start in HH:mm format. Required when mode is schedule. |
runtimeKeepAliveEnd | body | no | string | — | Daily runtime keep-alive window end in HH:mm format. Required when mode is schedule. |
runtimeKeepAliveTimezone | body | no | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC" | IANA timezone used to evaluate the runtime keep-alive window. |
buildExecutionPlan | body | no | string | — | Execution plan for function deployment builds. Omit to use the legacy default. |
runtimeExecutionPlan | body | no | string | — | Execution plan for function executions. Omit to use the legacy default. |
deploymentRetention | body | no | integer | format=int32; default=0 | Days to keep non-active deployments before deletion. Value 0 means all deployments will be kept. |
Success response: HTTP 201 — function.
Response fields: $id (string), $createdAt (string), $updatedAt (string), execute (array), name (string), enabled (boolean), live (boolean), logging (boolean), runtime (string), deploymentRetention (integer), deploymentId (string), deploymentCreatedAt (string), latestDeploymentId (string), latestDeploymentCreatedAt (string), latestDeploymentStatus (string), scopes (array), vars (array), events (array), schedule (string), timeout (integer), entrypoint (string), commands (string), version (string), installationId (string), providerRepositoryId (string), providerBranch (string), providerRootDirectory (string), providerSilentMode (boolean), buildSpecification (string), runtimeSpecification (string), runtimeReplicas (integer), runtimeKeepAliveMode (string), runtimeKeepAliveStart (string), runtimeKeepAliveEnd (string), runtimeKeepAliveTimezone (string), buildExecutionPlan (string), runtimeExecutionPlan (string).
PUT /functions/{functionId}
Update function
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
functionId | path | yes | string | — | Function ID. |
name | body | yes | string | — | Function name. Max length: 128 chars. |
runtime | body | no | string | enum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 …; default="" | Execution runtime. |
execute | body | no | array[string] | default=[] | 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 | body | no | array[string] | default=[] | Events list. Maximum of 100 events are allowed. |
schedule | body | no | string | default="" | Schedule CRON syntax. |
timeout | body | no | integer | format=int32; default=15 | Maximum execution time in seconds. |
enabled | body | no | boolean | default=true | 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 | body | no | boolean | default=true | When disabled, executions will exclude logs and errors, and will be slightly faster. |
entrypoint | body | no | string | default="" | Entrypoint File. This path is relative to the "providerRootDirectory". |
commands | body | no | string | default="" | Build Commands. |
scopes | body | no | array[string] | default=[] | List of scopes allowed for API Key auto-generated for every execution. Maximum of 100 scopes are allowed. |
installationId | body | no | string | default="" | Agentbase Installation ID for VCS (Version Controle System) deployment. |
providerRepositoryId | body | no | string | — | Repository ID of the repo linked to the function |
providerBranch | body | no | string | default="" | Production branch for the repo linked to the function |
providerSilentMode | body | no | boolean | default=false | 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 | body | no | string | default="" | Path to function code in the linked repo. |
buildSpecification | body | no | string | default="s-1vcpu-2gb" | Build specification is fixed to the platform Function build profile. |
runtimeSpecification | body | no | string | default={} | Runtime specification for the function executions. |
runtimeReplicas | body | no | integer | format=int32; default=1 | Number of reusable runtime replicas for function executions. Allowed values are 1, 2, 3, 5, and 10. |
runtimeKeepAliveMode | body | no | string | enum=disabled, always, schedule; default="disabled" | Runtime keep-alive mode. Allowed values are disabled, always, and schedule. Omit to keep the current value. |
runtimeKeepAliveStart | body | no | string | — | Daily runtime keep-alive window start in HH:mm format. Required when mode is schedule. Omit to keep the current value. |
runtimeKeepAliveEnd | body | no | string | — | Daily runtime keep-alive window end in HH:mm format. Required when mode is schedule. Omit to keep the current value. |
runtimeKeepAliveTimezone | body | no | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC" | IANA timezone used to evaluate the runtime keep-alive window. Omit to keep the current value. |
buildExecutionPlan | body | no | string | — | Execution plan for function deployment builds. Omit to keep the current value. |
runtimeExecutionPlan | body | no | string | — | Execution plan for function executions. Omit to keep the current value. |
deploymentRetention | body | no | integer | format=int32; default=0 | Days to keep non-active deployments before deletion. Value 0 means all deployments will be kept. |
Success response: HTTP 200 — function.
Response fields: $id (string), $createdAt (string), $updatedAt (string), execute (array), name (string), enabled (boolean), live (boolean), logging (boolean), runtime (string), deploymentRetention (integer), deploymentId (string), deploymentCreatedAt (string), latestDeploymentId (string), latestDeploymentCreatedAt (string), latestDeploymentStatus (string), scopes (array), vars (array), events (array), schedule (string), timeout (integer), entrypoint (string), commands (string), version (string), installationId (string), providerRepositoryId (string), providerBranch (string), providerRootDirectory (string), providerSilentMode (boolean), buildSpecification (string), runtimeSpecification (string), runtimeReplicas (integer), runtimeKeepAliveMode (string), runtimeKeepAliveStart (string), runtimeKeepAliveEnd (string), runtimeKeepAliveTimezone (string), buildExecutionPlan (string), runtimeExecutionPlan (string).
GET /projects/{projectId}/schedules
List schedules
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Project unique ID. |
queries | query | no | array[string] | default=[] | 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: resourceType, resourceId, projectId, schedule, scheduleType, purpose, compact, active, region |
total | query | no | boolean | default=true | When set to false, the total count returned will be 0 and will not be calculated. |
Success response: HTTP 200 — scheduleList.
Response fields: total (integer), schedules (array), hasMore (boolean).
POST /projects/{projectId}/schedules
Create schedule
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Project unique ID. |
resourceType | body | yes | string | enum=functions, function, multi-cron-function, execution, message | The resource type for the schedule. Possible values: functions, function, multi-cron-function, execution, message. |
resourceId | body | yes | string | — | The resource ID to associate with this schedule. |
schedule | body | yes | string | — | Cron expression or JSON rule for scheduleType. |
active | body | no | boolean | default=false | Whether the schedule is active. |
data | body | no | string | — | Schedule data as a JSON string. Used to store resource-specific context needed for execution. |
scheduleType | body | no | string | enum=cron, interval, quartz; default="cron" | Recurring function rule type. Immutable after creation. |
Success response: HTTP 201 — schedule.
Response fields: $id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
GET /projects/{projectId}/schedules/{scheduleId}
Get schedule
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Project unique ID. |
scheduleId | path | yes | string | — | Schedule ID. |
Success response: HTTP 200 — schedule.
Response fields: $id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
PATCH /projects/{projectId}/schedules/{scheduleId}
Update schedule
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Project unique ID. |
scheduleId | path | yes | string | — | Schedule unique ID. |
schedule | body | no | string | — | Rule expression or JSON for the existing schedule type. |
active | body | no | boolean | — | Whether the schedule is active. |
data | body | no | string | — | JSON object text; body contains JSON text sent to the function. |
scheduleType | body | no | string | enum=cron, interval, quartz | Existing rule type. Changing the type is not allowed. |
Success response: HTTP 200 — schedule.
Response fields: $id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
DELETE /projects/{projectId}/schedules/{scheduleId}
Delete schedule
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
projectId | path | yes | string | — | Project unique ID. |
scheduleId | path | yes | string | — | Schedule unique ID. |
Success response: HTTP 204 — No content.
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.