Docs
Contents

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

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 + pathPurpose
GET /functionsList functions
POST /functionsCreate a function
GET /functions/{functionId}Get a function
PUT /functions/{functionId}Update function configuration
DELETE /functions/{functionId}Delete a function
PATCH /functions/{functionId}/deploymentSwitch the active deployment
GET /functions/{functionId}/deploymentsList deployments
POST /functions/{functionId}/deploymentsCreate a deployment by uploading code
POST /functions/{functionId}/deployments/duplicateDuplicate an existing deployment
POST /functions/{functionId}/deployments/templateCreate a deployment from a template
POST /functions/{functionId}/deployments/vcsCreate a deployment from a VCS branch/commit
GET /functions/{functionId}/deployments/{deploymentId}Get a deployment
GET /functions/{functionId}/deployments/{deploymentId}/downloadDownload the deployment artifact
PATCH /functions/{functionId}/deployments/{deploymentId}/statusManually mark deployment status
DELETE /functions/{functionId}/deployments/{deploymentId}Delete a deployment
POST /functions/{functionId}/executionsExecute a function
GET /functions/{functionId}/executionsList execution records
GET /functions/{functionId}/executions/{executionId}Get an execution record
GET /functions/{functionId}/execution-pathsPaginated list of deduplicated request paths (from 2.10.0 onwards, +path / pathMatch / method filters)
GET /functions/{functionId}/execution-paths/executionsQuery 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-statusRuntime status (replicas/keep-alive)
GET /functions/{functionId}/variablesList function variables
POST /functions/{functionId}/variablesCreate 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/runtimesList available runtimes (public)
GET /functions/specificationsList build/run specifications
GET /functions/execution-plansList execution plans

Endpoint details

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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []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.
searchquerystringNo—Search term that fuzzily filters list results. Up to 256 characters.
totalquerybooleanNoDefault trueWhen 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:

FieldTypeDescription
$idstringFunction ID.
$createdAtstringFunction creation time (ISO 8601).
$updatedAtstringFunction update time (ISO 8601).
executestring[]Array of roles that can execute this function.
namestringFunction name.
enabledbooleanWhether the function is enabled.
livebooleanWhether 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.
loggingbooleanWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
runtimestringRuntime used for function build and execution.
deploymentIdstringID of the currently active deployment.
latestDeploymentIdstringID of the latest (not necessarily active) deployment.
latestDeploymentStatusstringStatus of the latest deployment: waiting / processing / building / ready / failed.
scopesstring[]List of scopes allowed for execution-level auto-generated API Keys.
eventsstring[]List of trigger events.
schedulestringCRON-format scheduled expression.
timeoutintegerMaximum 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)

ParameterLocationTypeRequiredDefault/enumDescription
functionIdbodystringYes—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.
namebodystringYes—Function name. Up to 128 characters.
runtimebodystringYesnode-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.
executebodystring[]No—Array of role strings with execution permission. By default no roles are granted. Maximum of 100 roles, each up to 64 characters.
eventsbodystring[]No—List of trigger events. Maximum of 100.
schedulebodystringNo—CRON-format scheduled expression.
timeoutbodyintegerNo—Maximum execution time (seconds).
enabledbodybooleanNo—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.
loggingbodybooleanNo—When disabled, execution records do not include logs and errors, and execution is slightly faster.
entrypointbodystringNo—Entry file. Path is relative to providerRootDirectory.
commandsbodystringNo—Build command.
scopesbodystring[]No—List of scopes allowed for the API Key auto-generated per execution. Maximum of 100.
installationIdbodystringNo—AppBase installation ID used for VCS deployment.
providerRepositoryIdbodystringNo—VCS repository ID associated with the function.
providerBranchbodystringNo—Production branch of the repository associated with the function.
providerSilentModebodybooleanNo—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.
providerRootDirectorybodystringNo—Path of the function code in the associated repository.
buildSpecificationbodystringNo—Build spec is fixed to the platform function build tier.
runtimeSpecificationbodystringNo—Runtime spec used for function execution.
runtimeReplicasbodyintegerNo—Number of reusable resident runtime replicas for function execution. Allowed values: 1 / 2 / 3 / 5 / 10.
runtimeKeepAliveModebodystringNodisabled / always / scheduleRuntime keep-alive mode: disabled / always / schedule.
runtimeKeepAliveStartbodystringNoMay be nullDaily keep-alive window start time (HH:mm). Required in schedule mode.
runtimeKeepAliveEndbodystringNoMay be nullDaily keep-alive window end time (HH:mm). Required in schedule mode.
runtimeKeepAliveTimezonebodystringNoafrica/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.
buildExecutionPlanbodystringNoMay be nullExecution plan used for function deployment builds. Omit to use legacy defaults.
runtimeExecutionPlanbodystringNoMay be nullExecution plan used for function execution. Omit to use legacy defaults.
deploymentRetentionbodyintegerNo—Number of retention days before non-active deployments are deleted. 0 means retain all.

Output: 201, model function, fields:

FieldTypeDescription
$idstringFunction ID.
$createdAtstringFunction creation time (ISO 8601).
$updatedAtstringFunction update time (ISO 8601).
executestring[]Array of roles that can execute this function.
namestringFunction name.
enabledbooleanWhether the function is enabled.
livebooleanWhether 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.
loggingbooleanWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
runtimestringRuntime used for function build and execution.
deploymentRetentionintegerRetention days for non-active deployments; they are automatically deleted upon expiry.
deploymentIdstringID of the currently active deployment.
deploymentCreatedAtstringCreation time of the active deployment (ISO 8601).
latestDeploymentIdstringID of the latest (not necessarily active) deployment.
latestDeploymentCreatedAtstringCreation time of the latest deployment (ISO 8601).
latestDeploymentStatusstringStatus of the latest deployment: waiting / processing / building / ready / failed.
scopesstring[]List of scopes allowed for execution-level auto-generated API Keys.
varsvariable[]List of function variables.
eventsstring[]List of trigger events.
schedulestringCRON-format scheduled expression.
timeoutintegerMaximum execution time (seconds).
entrypointstringEntry file of the deployed code.
commandsstringBuild command of the deployment.
versionstringOpen Runtimes version used by the function.
installationIdstringVCS (version control system) installation ID associated with the function.
providerRepositoryIdstringVCS (version control system) repository ID.
providerBranchstringVCS (version control system) branch name.
providerRootDirectorystringPath of the function code in the VCS repository.
providerSilentModebooleanWhether the VCS connection is in silent mode. In silent mode, no comments are posted on the repository's PRs / MRs.
buildSpecificationstringFixed machine spec used for builds (CPU/memory tier).
runtimeSpecificationstringMachine spec used for execution (CPU/memory tier).
runtimeReplicasintegerNumber of reusable resident runtime replicas for function execution.
runtimeKeepAliveModestringRuntime keep-alive mode: disabled / always / schedule.
runtimeKeepAliveStartstringDaily keep-alive window start time (HH:mm).
runtimeKeepAliveEndstringDaily keep-alive window end time (HH:mm).
runtimeKeepAliveTimezonestringIANA time zone name used to evaluate the keep-alive window.
buildExecutionPlanstringExecution plan used for deployment builds.
runtimeExecutionPlanstringExecution 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.

Output: 200, model function (full fields described above), key fields:

FieldTypeDescription
$idstringFunction ID.
$createdAtstringFunction creation time (ISO 8601).
$updatedAtstringFunction update time (ISO 8601).
executestring[]Array of roles that can execute this function.
namestringFunction name.
enabledbooleanWhether the function is enabled.
livebooleanWhether 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.
loggingbooleanWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
runtimestringRuntime used for function build and execution.
deploymentIdstringID of the currently active deployment.
latestDeploymentIdstringID of the latest (not necessarily active) deployment.
latestDeploymentStatusstringStatus of the latest deployment: waiting / processing / building / ready / failed.
scopesstring[]List of scopes allowed for execution-level auto-generated API Keys.
eventsstring[]List of trigger events.
schedulestringCRON-format scheduled expression.
timeoutintegerMaximum 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)

ParameterLocationTypeRequiredDefault/enumDescription
namebodystringYes—Function name. Up to 128 characters.
runtimebodystringNonode-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 valueexecution runtime.
executebodystring[]No[]Array of role strings with execution permission. By default no roles are granted. Maximum of 100 roles, each up to 64 characters.
eventsbodystring[]No[]List of trigger events. Maximum of 100.
schedulebodystringNoOmission preserves current valueCRON expression. A non-empty update requires exactly one existing compact execution schedule; a missing rule errors and multiple rules conflict.
timeoutbodyintegerNo15Maximum execution time (seconds).
enabledbodybooleanNotrueWhether 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.
loggingbodybooleanNotrueWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
entrypointbodystringNoEmpty value retains current entrypointEntry file. Path is relative to providerRootDirectory.
commandsbodystringNo""Build command.
scopesbodystring[]No[]List of scopes allowed for the API Key auto-generated per execution. Maximum of 100.
installationIdbodystringNo""AppBase installation ID used for VCS deployment.
providerRepositoryIdbodystringNonullID of the VCS repository associated with the function.
providerBranchbodystringNo""Production branch of the repository associated with the function.
providerSilentModebodybooleanNofalseWhether 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.
providerRootDirectorybodystringNo""Path of the function code in the associated repository.
buildSpecificationbodystringNoPlatform-fixed build specificationBuild spec is fixed to the platform function build tier.
runtimeSpecificationbodystringNoOmission preserves current valueRuntime spec used for function execution.
runtimeReplicasbodyintegerNoOmission preserves current valueNumber of reusable resident runtime replicas for function execution. Allowed values: 1 / 2 / 3 / 5 / 10.
runtimeKeepAliveModebodystringNodisabled / always / schedule;Omission preserves current valueRuntime keep-alive mode: disabled / always / schedule. Omit to keep the current value.
runtimeKeepAliveStartbodystringNoOmission uses current value; non-schedule mode normalizes it to nullDaily keep-alive window start time (HH:mm). Required in schedule mode.
runtimeKeepAliveEndbodystringNoOmission uses current value; non-schedule mode normalizes it to nullDaily keep-alive window end time (HH:mm). Required in schedule mode.
runtimeKeepAliveTimezonebodystringNoOmission preserves current valueIANA time zone name used to evaluate the keep-alive window. Omit to keep the current value.
buildExecutionPlanbodystringNoOmission preserves current valueExecution plan used for the function deployment build. Omit to keep the current value.
runtimeExecutionPlanbodystringNoOmission preserves current valueExecution plan used for function execution. Omit to keep the current value.
deploymentRetentionbodyintegerNo0Number of retention days before non-active deployments are deleted. 0 means retain all.
functionIdpathstringYes—Function ID.

Output: 200, model function (full fields described above), key fields:

FieldTypeDescription
$idstringFunction ID.
$createdAtstringFunction creation time (ISO 8601).
$updatedAtstringFunction update time (ISO 8601).
executestring[]Array of roles that can execute this function.
namestringFunction name.
enabledbooleanWhether the function is enabled.
livebooleanWhether 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.
loggingbooleanWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
runtimestringRuntime used for function build and execution.
deploymentIdstringID of the currently active deployment.
latestDeploymentIdstringID of the latest (not necessarily active) deployment.
latestDeploymentStatusstringStatus of the latest deployment: waiting / processing / building / ready / failed.
scopesstring[]List of scopes allowed for execution-level auto-generated API Keys.
eventsstring[]List of trigger events.
schedulestringCRON-format scheduled expression.
timeoutintegerMaximum 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—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)

ParameterLocationTypeRequiredDefault/enumDescription
deploymentIdbodystringYes—Deployment ID.
functionIdpathstringYes—Function ID.

Output: 200, model function (full fields described above), key fields:

FieldTypeDescription
$idstringFunction ID.
$createdAtstringFunction creation time (ISO 8601).
$updatedAtstringFunction update time (ISO 8601).
executestring[]Array of roles that can execute this function.
namestringFunction name.
enabledbooleanWhether the function is enabled.
livebooleanWhether 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.
loggingbooleanWhen disabled, execution records do not include logs and errors, and execution is slightly faster.
runtimestringRuntime used for function build and execution.
deploymentIdstringID of the currently active deployment.
latestDeploymentIdstringID of the latest (not necessarily active) deployment.
latestDeploymentStatusstringStatus of the latest deployment: waiting / processing / building / ready / failed.
scopesstring[]List of scopes allowed for execution-level auto-generated API Keys.
eventsstring[]List of trigger events.
schedulestringCRON-format scheduled expression.
timeoutintegerMaximum 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
queriesquerystring[]NoDefault []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.
searchquerystringNo—Search term that fuzzily filters list results. Up to 256 characters.
totalquerybooleanNoDefault trueWhen 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:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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")

ParameterLocationTypeRequiredDefault/enumDescription
entrypointbody (form)stringNoNullable nullEntry file.
commandsbody (form)stringNoNullable nullBuild command.
codebody (form)stringYes—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.
artifactModebody (form)stringNosource / 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).
activatebody (form)booleanYes—Whether to automatically activate this deployment after the build completes.
functionIdpathstringYes—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:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
$updatedAtstringDeployment update time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
screenshotLightstringFile ID of the light-theme screenshot.
screenshotDarkstringFile ID of the dark-theme screenshot.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildLogsstringBuild logs.
buildDurationintegerCurrent build duration (seconds).
providerRepositoryNamestringVCS provider repository name.
providerRepositoryOwnerstringVCS repository owner name.
providerRepositoryUrlstringVCS repository URL.
providerCommitHashstringVCS commit hash.
providerCommitAuthorUrlstringVCS commit author profile page.
providerCommitAuthorstringVCS commit author name.
providerCommitMessagestringCommit message.
providerCommitUrlstringVCS commit URL.
providerBranchstringVCS repository branch.
providerBranchUrlstringVCS 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)

ParameterLocationTypeRequiredDefault/enumDescription
deploymentIdbodystringYes—Deployment ID.
buildIdbodystringNo—ID of this build.
functionIdpathstringYes—Function ID.

Output: 202, model deployment (full fields described above), key fields:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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)

ParameterLocationTypeRequiredDefault/enumDescription
repositorybodystringYes—Template repository name.
ownerbodystringYes—Template repository owner.
rootDirectorybodystringYes—Path of the function code within the template repository.
typebodystringYescommit / branch / tagType of the reference: commit / branch / tag.
referencebodystringYes—Value of the reference: commit hash, branch name, or release tag.
activatebodybooleanNo—Whether to automatically activate this deployment after the build completes.
functionIdpathstringYes—Function ID.

Output: 202, model deployment (full fields described above), key fields:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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)

ParameterLocationTypeRequiredDefault/enumDescription
typebodystringYesbranch / commitType of the reference: branch / commit.
referencebodystringYes—VCS reference used to create the deployment: branch name or commit hash (depending on type).
activatebodybooleanNo—Whether to automatically activate this deployment after the build completes.
functionIdpathstringYes—Function ID.

Output: 202, model deployment (full fields described above), key fields:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
deploymentIdpathstringYes—Deployment ID.

Output: 200, model deployment (full fields described above), key fields:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
deploymentIdpathstringYes—Deployment ID.
typequerystringNosource / 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
deploymentIdpathstringYes—Deployment ID.

Output: 200, model deployment (full fields described above), key fields:

FieldTypeDescription
$idstringDeployment ID.
$createdAtstringDeployment creation time (ISO 8601).
typestringDeployment type.
artifactModestringUpload mode: source / java-jar (added in 2.10.0).
resourceIdstringID of the owning resource.
resourceTypestringType of the owning resource.
entrypointstringEntry file used by the deployment to execute code.
sourceSizeintegerSource package size (bytes).
buildSizeintegerBuild artifact size (bytes).
totalSizeintegerTotal size (source + build artifact, bytes).
buildIdstringCurrent build ID.
activatebooleanWhether to automatically activate after the build completes.
statusstringDeployment status: waiting / processing / building / ready / canceled / failed.
buildDurationintegerCurrent 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
deploymentIdpathstringYes—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)

ParameterLocationTypeRequiredDefault/enumDescription
bodybodystringNo—Execution request body. Defaults to an empty string.
asyncbodybooleanNo—Whether to execute in the background. Default false.
pathbodystringNo—Execution path, may include query parameters. Default /.
methodbodystringNoGET / POST / PUT / PATCH / DELETE / OPTIONS / HEADHTTP method. Defaults to POST.
headersbodyobjectNo—Execution request headers. Empty by default.
scheduledAtbodystringNoCan be nullScheduled execution time (ISO 8601). Must be a future time, with minute-level precision.
functionIdpathstringYes—Function ID.

Output: 201, model execution, fields:

FieldTypeDescription
$idstringExecution record ID.
$createdAtstringExecution record creation time (ISO 8601).
$updatedAtstringExecution record update time (ISO 8601).
$permissionsstring[]Execution role.
functionIdstringFunction ID.
deploymentIdstringID of the deployment used to trigger this execution.
triggerstringTrigger source: http / schedule / event.
statusstringExecution status: waiting / processing / completed / failed / scheduled.
requestMethodstringHTTP request method.
requestPathstringHTTP request path (may include the query string).
requestHeadersheaders[]HTTP request header key-value object. Only whitelisted headers are returned; executions created synchronously return all request headers.
responseStatusCodeintegerHTTP response status code.
responseBodystringHTTP response body returned by the function.
responseHeadersheaders[]HTTP response header key-value object. Only whitelisted headers are returned; executions created synchronously return all response headers.
logsstringFunction logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string.
errorsstringFunction 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.
durationnumberExecution duration of the resource (function/site) in seconds.
scheduledAtstringScheduled 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
queriesquerystring[]NoDefault []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.
totalquerybooleanNoDefault trueWhen set to false, skips total count calculation and the returned total is fixed at 0.
pathquerystringNoEmpty by defaultFull request path or regex; the query string participates in matching. In the Node Server object, the parameter name is xpath.
pathMatchquerystringNoexact / regex, default exactRegex must not carry /…/ delimiters; invalid expressions are rejected.
methodquerystringNoGET / POST / PUT / PATCH / DELETE / HEAD / OPTIONSTakes 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:

FieldTypeDescription
$idstringExecution record ID.
$createdAtstringExecution record creation time (ISO 8601).
functionIdstringFunction ID.
deploymentIdstringID of the deployment used to trigger this execution.
triggerstringTrigger source: http / schedule / event.
statusstringExecution status: waiting / processing / completed / failed / scheduled.
requestMethodstringHTTP request method.
requestPathstringHTTP request path (may include the query string).
responseStatusCodeintegerHTTP response status code.
responseBodystringHTTP response body returned by the function.
logsstringFunction logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string.
errorsstringFunction 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.
durationnumberExecution 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
executionIdpathstringYes—Execution record ID.

Output: 200, model execution (full fields described above), key fields:

FieldTypeDescription
$idstringExecution record ID.
$createdAtstringExecution record creation time (ISO 8601).
functionIdstringFunction ID.
deploymentIdstringID of the deployment used to trigger this execution.
triggerstringTrigger source: http / schedule / event.
statusstringExecution status: waiting / processing / completed / failed / scheduled.
requestMethodstringHTTP request method.
requestPathstringHTTP request path (may include the query string).
responseStatusCodeintegerHTTP response status code.
responseBodystringHTTP response body returned by the function.
logsstringFunction logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string.
errorsstringFunction 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.
durationnumberExecution 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
executionIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
limitqueryintegerNo25Maximum number of records to return.
offsetqueryintegerNo0Number of records to skip.
totalquerybooleanNotrueWhether to compute the total count; when false, the returned total is 0.
pathquerystringNo—Filter by request path (added in 2.10.0); combine with pathMatch to choose exact or regex matching.
pathMatchquerystringNoexact / regex (default exact)Path matching mode (added in 2.10.0).
methodquerystringNoGET / POST / PUT / PATCH / DELETE / OPTIONS / HEADFilter by HTTP method (added in 2.10.0).

output: 200, model executionPathList.

FieldTypeDescription
totalintegerTotal number of deduplicated request paths.
pathsstring[]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:

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
pathquerystringYes—Execution request path; exact match by default, regex when pathMatch=regex (since 2.10.0).
queriesquerystring[]No[]Array of SDK Query strings; at most 100 items, each up to 4096 characters.
totalquerybooleanNotrueWhether to compute the total count; when false, the returned total is 0.
pathMatchquerystringNoexact / regex (default exact)Path matching mode (added in 2.10.0).
methodquerystringNoGET / POST / PUT / PATCH / DELETE / OPTIONS / HEADFilter 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.

Output: 200, model runtimeStatus, fields:

FieldTypeDescription
statusstringRuntime status summary.
coveragestringCoverage of the status data.
updatedAtstringLast update time of the underlying resource.
messagestringUser-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:

FieldTypeDescription
$idstringRuntime ID.
keystringKey name of the owning runtime.
namestringRuntime name.
versionstringRuntime version.
basestringBase Docker image used to build this runtime.
imagestringDocker Hub image name.
supportsstring[]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:

FieldTypeDescription
memoryintegerMemory size (MB).
cpusnumberNumber of CPU cores.
enabledbooleanWhether this specification is enabled.
slugstringSpecification 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

ParameterLocationTypeRequiredDefault/enumDescription
runtimequerystringNonode-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:

FieldTypeDescription
idstringStable execution plan ID.
namestringExecution plan display name.
summarystringExecution plan description.
suitableForstringResource type supported by this execution plan.
recommendedbooleanWhether this is a recommended execution plan.
availabilitystringAvailability of this execution plan.
effectiveOnstringEffective 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—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:

FieldTypeDescription
$idstringVariable ID.
keystringVariable key name.
valuestringVariable value.
secretbooleanWhether it is a secret variable. Secret variables can only be updated or deleted, not read.
resourceTypestringService the variable belongs to: project / function.
resourceIdstringID 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)

ParameterLocationTypeRequiredDefault/enumDescription
keybodystringYes—Variable key name. Up to 255 characters.
valuebodystringYes—Variable value. Up to 8192 characters.
secretbodybooleanNo—Secret variables can be updated/deleted, but only the function can read them at build and run time.
functionIdpathstringYes—Function ID.

Output: 201, model variable, fields:

FieldTypeDescription
$idstringVariable ID.
$createdAtstringVariable creation time (ISO 8601).
$updatedAtstringVariable creation time (ISO 8601).
keystringVariable key name.
valuestringVariable value.
secretbooleanWhether it is a secret variable. Secret variables can only be updated or deleted, not read.
resourceTypestringService the variable belongs to: project / function.
resourceIdstringID 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
variableIdpathstringYes—Variable ID.

Output: 200, model variable (full fields described above), key fields:

FieldTypeDescription
$idstringVariable ID.
keystringVariable key name.
valuestringVariable value.
secretbooleanWhether it is a secret variable. Secret variables can only be updated or deleted, not read.
resourceTypestringService the variable belongs to: project / function.
resourceIdstringID 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)

ParameterLocationTypeRequiredDefault/enumDescription
keybodystringYes—Variable key name. Up to 255 characters.
valuebodystringNoCan be a nullvariable value. Maximum 8192 characters.
secretbodybooleanNoCan be a nullSecret variables can be updated/deleted, but only functions can read them at build and runtime.
functionIdpathstringYes—Function ID.
variableIdpathstringYes—Variable ID.

Output: 200, model variable (full fields described above), key fields:

FieldTypeDescription
$idstringVariable ID.
keystringVariable key name.
valuestringVariable value.
secretbooleanWhether it is a secret variable. Secret variables can only be updated or deleted, not read.
resourceTypestringService the variable belongs to: project / function.
resourceIdstringID 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

ParameterLocationTypeRequiredDefault/enumDescription
functionIdpathstringYes—Function ID.
variableIdpathstringYes—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

Correspondence with the Server SDK

service.methodEndpoint
Functions.list / create / get / update / delete/functions CRUD
Functions.updateFunctionDeploymentPATCH /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.getRuntimeStatusGET /functions/{functionId}/runtime-status
Functions.listVariables / createVariable / getVariable / updateVariable / deleteVariable/functions/{functionId}/variables*
Functions.listRuntimesGET /functions/runtimes
Functions.listSpecificationsGET /functions/specifications
Functions.listExecutionPlansGET /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.

HTTPScopeSDK
POST /functionsfunctions.writefunctions.create
PUT /functions/{functionId}functions.writefunctions.update
GET /projects/{projectId}/schedulesschedules.readprojects.listSchedules
POST /projects/{projectId}/schedulesschedules.writeprojects.createSchedule
GET /projects/{projectId}/schedules/{scheduleId}schedules.readprojects.getSchedule
PATCH /projects/{projectId}/schedules/{scheduleId}schedules.writeprojects.updateSchedule
DELETE /projects/{projectId}/schedules/{scheduleId}schedules.writeprojects.deleteSchedule

POST /functions

Create function

ParameterLocationRequiredTypeConstraints / defaultMeaning
functionIdbodyyesstring—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.
namebodyyesstring—Function name. Max length: 128 chars.
runtimebodyyesstringenum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 …Execution runtime.
executebodynoarray[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.
eventsbodynoarray[string]default=[]Events list. Maximum of 100 events are allowed.
schedulebodynostringdefault=""Schedule CRON syntax.
timeoutbodynointegerformat=int32; default=15Function maximum execution time in seconds.
enabledbodynobooleandefault=trueIs 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.
loggingbodynobooleandefault=trueWhen disabled, executions will exclude logs and errors, and will be slightly faster.
entrypointbodynostringdefault=""Entrypoint File. This path is relative to the "providerRootDirectory".
commandsbodynostringdefault=""Build Commands.
scopesbodynoarray[string]default=[]List of scopes allowed for API key auto-generated for every execution. Maximum of 100 scopes are allowed.
installationIdbodynostringdefault=""Agentbase Installation ID for VCS (Version Control System) deployment.
providerRepositoryIdbodynostringdefault=""Repository ID of the repo linked to the function.
providerBranchbodynostringdefault=""Production branch for the repo linked to the function.
providerSilentModebodynobooleandefault=falseIs 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.
providerRootDirectorybodynostringdefault=""Path to function code in the linked repo.
buildSpecificationbodynostringdefault="s-1vcpu-2gb"Build specification is fixed to the platform Function build profile.
runtimeSpecificationbodynostringdefault={}Runtime specification for the function executions.
runtimeReplicasbodynointegerformat=int32; default=1Number of reusable runtime replicas for function executions. Allowed values are 1, 2, 3, 5, and 10.
runtimeKeepAliveModebodynostringenum=disabled, always, schedule; default="disabled"Runtime keep-alive mode. Allowed values are disabled, always, and schedule.
runtimeKeepAliveStartbodynostring—Daily runtime keep-alive window start in HH:mm format. Required when mode is schedule.
runtimeKeepAliveEndbodynostring—Daily runtime keep-alive window end in HH:mm format. Required when mode is schedule.
runtimeKeepAliveTimezonebodynostringenum=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.
buildExecutionPlanbodynostring—Execution plan for function deployment builds. Omit to use the legacy default.
runtimeExecutionPlanbodynostring—Execution plan for function executions. Omit to use the legacy default.
deploymentRetentionbodynointegerformat=int32; default=0Days 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

ParameterLocationRequiredTypeConstraints / defaultMeaning
functionIdpathyesstring—Function ID.
namebodyyesstring—Function name. Max length: 128 chars.
runtimebodynostringenum=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.
executebodynoarray[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.
eventsbodynoarray[string]default=[]Events list. Maximum of 100 events are allowed.
schedulebodynostringdefault=""Schedule CRON syntax.
timeoutbodynointegerformat=int32; default=15Maximum execution time in seconds.
enabledbodynobooleandefault=trueIs 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.
loggingbodynobooleandefault=trueWhen disabled, executions will exclude logs and errors, and will be slightly faster.
entrypointbodynostringdefault=""Entrypoint File. This path is relative to the "providerRootDirectory".
commandsbodynostringdefault=""Build Commands.
scopesbodynoarray[string]default=[]List of scopes allowed for API Key auto-generated for every execution. Maximum of 100 scopes are allowed.
installationIdbodynostringdefault=""Agentbase Installation ID for VCS (Version Controle System) deployment.
providerRepositoryIdbodynostring—Repository ID of the repo linked to the function
providerBranchbodynostringdefault=""Production branch for the repo linked to the function
providerSilentModebodynobooleandefault=falseIs 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.
providerRootDirectorybodynostringdefault=""Path to function code in the linked repo.
buildSpecificationbodynostringdefault="s-1vcpu-2gb"Build specification is fixed to the platform Function build profile.
runtimeSpecificationbodynostringdefault={}Runtime specification for the function executions.
runtimeReplicasbodynointegerformat=int32; default=1Number of reusable runtime replicas for function executions. Allowed values are 1, 2, 3, 5, and 10.
runtimeKeepAliveModebodynostringenum=disabled, always, schedule; default="disabled"Runtime keep-alive mode. Allowed values are disabled, always, and schedule. Omit to keep the current value.
runtimeKeepAliveStartbodynostring—Daily runtime keep-alive window start in HH:mm format. Required when mode is schedule. Omit to keep the current value.
runtimeKeepAliveEndbodynostring—Daily runtime keep-alive window end in HH:mm format. Required when mode is schedule. Omit to keep the current value.
runtimeKeepAliveTimezonebodynostringenum=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.
buildExecutionPlanbodynostring—Execution plan for function deployment builds. Omit to keep the current value.
runtimeExecutionPlanbodynostring—Execution plan for function executions. Omit to keep the current value.
deploymentRetentionbodynointegerformat=int32; default=0Days 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

ParameterLocationRequiredTypeConstraints / defaultMeaning
projectIdpathyesstring—Project unique ID.
queriesquerynoarray[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
totalquerynobooleandefault=trueWhen 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

ParameterLocationRequiredTypeConstraints / defaultMeaning
projectIdpathyesstring—Project unique ID.
resourceTypebodyyesstringenum=functions, function, multi-cron-function, execution, messageThe resource type for the schedule. Possible values: functions, function, multi-cron-function, execution, message.
resourceIdbodyyesstring—The resource ID to associate with this schedule.
schedulebodyyesstring—Cron expression or JSON rule for scheduleType.
activebodynobooleandefault=falseWhether the schedule is active.
databodynostring—Schedule data as a JSON string. Used to store resource-specific context needed for execution.
scheduleTypebodynostringenum=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

ParameterLocationRequiredTypeConstraints / defaultMeaning
projectIdpathyesstring—Project unique ID.
scheduleIdpathyesstring—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

ParameterLocationRequiredTypeConstraints / defaultMeaning
projectIdpathyesstring—Project unique ID.
scheduleIdpathyesstring—Schedule unique ID.
schedulebodynostring—Rule expression or JSON for the existing schedule type.
activebodynoboolean—Whether the schedule is active.
databodynostring—JSON object text; body contains JSON text sent to the function.
scheduleTypebodynostringenum=cron, interval, quartzExisting 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

ParameterLocationRequiredTypeConstraints / defaultMeaning
projectIdpathyesstring—Project unique ID.
scheduleIdpathyesstring—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.