Sites API
Full lifecycle interfaces for sites: create sites (multiple frontend frameworks, dual static/SSR rendering strategy), code/template/VCS deployment, build and runtime status, SSR runtime logs, and site variables. Isomorphic in shape to the deployment/execution interfaces of functions.
Service and resource boundaries
The Sites API (/v1/sites/*) provides build, hosting, and server-side rendering (SSR) management capabilities for modern web frontends and full-stack applications (Next.js, Nuxt, SvelteKit, Astro, Remix, React/Vue SPAs, and static sites): it supports code archive upload, official template initialization, and Git VCS automatic builds, with built-in atomic cutover of deployment versions, SSR runtime replica monitoring, site-level environment variables, and edge access request log auditing.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/sites.Resources:
site({siteId}),deployment({deploymentId}),variable({variableId}), and request logs.Top-level enumeration endpoints:
/sites/frameworks(supported frameworks),/sites/specifications(build/runtime specs),/sites/execution-plans(execution plans).
Authentication and Permissions
For authentication and request header conventions, see General conventions. Scope of this domain: sites.read / sites.write (sites, deployments, variables, specs), log.read / log.write (request logs), public (frameworks list).
Endpoint overview
The Sites module provides 27 endpoints in total, covering: site CRUD and active deployment cutover (6), deployment build package management and artifact download (9), SSR request log query and cleanup (3), runtime status and site environment variable management (6), and enumeration of supported frontend frameworks, build specs, and execution plans (3).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /sites | List Sites |
POST /sites | Create Site |
GET /sites/{siteId} | Get Site |
PUT /sites/{siteId} | Update Site Configuration |
DELETE /sites/{siteId} | Delete Site |
PATCH /sites/{siteId}/deployment | Switch the active deployment |
GET /sites/{siteId}/deployments | List deployments |
POST /sites/{siteId}/deployments | Create a deployment by uploading code |
POST /sites/{siteId}/deployments/duplicate | Duplicate an existing deployment |
POST /sites/{siteId}/deployments/template | Create a deployment from a template |
POST /sites/{siteId}/deployments/vcs | Create a deployment from a VCS branch/commit |
GET /sites/{siteId}/deployments/{deploymentId} | Get a deployment |
GET /sites/{siteId}/deployments/{deploymentId}/download | Download the deployment artifact |
PATCH /sites/{siteId}/deployments/{deploymentId}/status | Manually mark deployment status |
DELETE /sites/{siteId}/deployments/{deploymentId} | Delete a deployment |
GET /sites/{siteId}/logs | SSR Request Log List |
GET /sites/{siteId}/logs/{logId} | Get Single Log |
DELETE /sites/{siteId}/logs/{logId} | Delete Log |
GET /sites/{siteId}/runtime-status | SSR Runtime Status |
GET /sites/{siteId}/variables | List Site Variables |
POST /sites/{siteId}/variables | Create a variable |
GET /sites/{siteId}/variables/{variableId} | Get a variable |
PUT /sites/{siteId}/variables/{variableId} | Update a variable |
DELETE /sites/{siteId}/variables/{variableId} | Delete a variable |
GET /sites/frameworks | List Supported Frameworks (public) |
GET /sites/specifications | List build/run specifications |
GET /sites/execution-plans | List execution plans |
Endpoint details
Site deployment (POST /v1/sites/{siteId}/deployments*) uses an asynchronous build pipeline; after uploading code, it returns a deployment object with a waiting / building status. When activate=true is provided, the build automatically cutover to the site's live production version once it reaches the ready terminal state, without a second call to PATCH /v1/sites/{siteId}/deployment.
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.
Site CRUD
GET /v1/sites
List all sites in a project with pagination, supporting filtering by name, framework, enabled status, and other attributes, plus keyword search (scope sites.read. SDK: Sites.list.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Query string array constructed by the SDK's Query builder (in the form limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: name, enabled, framework, deploymentId, buildCommand, installCommand, outputDirectory, installationId. At most 100 entries, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model siteList: total (total number of matches, not calculated when total=false) + sites[] (current page of data).
Key fields of the element model site:
| Field | Type | Description |
|---|---|---|
$id | string | Site ID. |
$createdAt | string | Site creation time (ISO 8601). |
$updatedAt | string | Site update time (ISO 8601). |
name | string | Site name. |
enabled | boolean | Whether the site is enabled. |
live | boolean | Whether the site has been deployed with the latest configuration. After modifying configuration such as variables/build commands, it becomes false; redeployment is required for changes to take effect. |
logging | boolean | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
framework | string | Site framework. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
timeout | integer | Maximum request duration (seconds). |
outputDirectory | string | Directory containing the site's build artifacts. |
adapter | string | Site framework adapter. |
fallbackFile | string | Fallback filename replacing the 404 page. When null, the platform default 404 page is shown. |
Call example:
curl -G "https://<your-endpoint>/v1/sites" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=landing"Response example:
{
"total": 5,
"sites": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "My Site",
"enabled": true,
"live": true,
"logging": true,
"framework": "nextjs",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"deploymentScreenshotLight": "5e5ea5c16897e",
"deploymentScreenshotDark": "5e5ea5c16897e",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
],
"timeout": 300,
"installCommand": "npm install",
"buildCommand": "npm run build",
"startCommand": "node custom-server.mjs",
"outputDirectory": "build",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "sites/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-512mb",
"runtimeSpecification": "s-1vcpu-512mb",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html"
}
]
}POST /v1/sites
Create a site: choose the frontend framework and rendering strategy (static/ssr), build/start commands, build/SSR specs, and execution plan (scope sites.write. SDK: Sites.create.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | body | string | Yes | — | Site 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. At most 36 characters. |
name | body | string | Yes | — | Site name. At most 128 characters. |
framework | body | string | Yes | analog / angular / nextjs / react / nuxt / vue / sveltekit / astro …… (see GET /sites/frameworks for the full list) | Site framework. |
enabled | body | boolean | No | — | Whether to enable the site. When disabled, it is inaccessible to users, but a Server SDK with an API Key can still access it; switching does not lose data. |
logging | body | boolean | No | — | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
timeout | body | integer | No | — | Maximum request duration (seconds). |
installCommand | body | string | No | — | Install command. |
buildCommand | body | string | No | — | Build command. |
startCommand | body | string | No | — | Custom start command. Leave empty to use the default. |
outputDirectory | body | string | No | — | Site build artifact directory. |
buildRuntime | body | string | Yes | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 …… (see GET /functions/runtimes for the full list) | Runtime used by the build step. |
adapter | body | string | No | static / ssr | Rendering strategy adapter: static (pure static) / ssr (server-side rendering). |
installationId | body | string | No | — | AppBase installation ID used for VCS deployment. |
fallbackFile | body | string | No | — | Fallback file for SPA sites. |
providerRepositoryId | body | string | No | — | ID of the VCS repository associated with the site. |
providerBranch | body | string | No | — | Production branch of the repository associated with the site. |
providerSilentMode | body | boolean | No | — | Whether the VCS connection for the associated repository is in silent mode. In silent mode, no comments are posted on commits and PRs. |
providerRootDirectory | body | string | No | — | Path of the site's code within the associated repository. |
buildSpecification | body | string | No | — | Build spec for the site deployment. |
runtimeSpecification | body | string | No | — | Runtime spec for SSR execution. |
buildExecutionPlan | body | string | No | Can be null | Execution plan used for the site deployment build. If omitted, the legacy default is used. |
runtimeExecutionPlan | body | string | No | Can be null | Execution plan used for SSR execution. If omitted, the legacy default is used. |
deploymentRetention | body | integer | No | — | Number of retention days before non-active deployments are deleted. 0 means retain all. |
Output: 201, model site, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Site ID. |
$createdAt | string | Site creation time (ISO 8601). |
$updatedAt | string | Site update time (ISO 8601). |
name | string | Site name. |
enabled | boolean | Whether the site is enabled. |
live | boolean | Whether the site has been deployed with the latest configuration. After modifying configuration such as variables/build commands, it becomes false; redeployment is required for changes to take effect. |
logging | boolean | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
framework | string | Site framework. |
deploymentRetention | integer | Retention days for non-active deployments; they are automatically deleted upon expiry. |
deploymentId | string | ID of the currently active deployment. |
deploymentCreatedAt | string | Creation time of the active deployment (ISO 8601). |
deploymentScreenshotLight | string | Screenshot file ID of the active deployment in light theme. |
deploymentScreenshotDark | string | Screenshot file ID of the active deployment in dark theme. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
latestDeploymentCreatedAt | string | Creation time of the latest deployment (ISO 8601). |
latestDeploymentStatus | string | Status of the latest deployment: waiting / processing / building / ready / failed. |
vars | variable[] | List of site variables. |
timeout | integer | Maximum request duration (seconds). |
installCommand | string | Command to install site dependencies. |
buildCommand | string | Command to build the site. |
startCommand | string | Custom command to start the site runtime. |
outputDirectory | string | Directory containing the site's build artifacts. |
installationId | string | VCS installation ID associated with the site. |
providerRepositoryId | string | VCS (version control system) repository ID. |
providerBranch | string | VCS (version control system) branch name. |
providerRootDirectory | string | Path of the site's code in the VCS repository. |
providerSilentMode | boolean | Whether the VCS connection is in silent mode. In silent mode, no comments are posted on the repository's PRs / MRs. |
buildSpecification | string | Machine spec used for builds (CPU/memory tier). |
runtimeSpecification | string | Machine spec used for SSR runtime (CPU/memory tier). |
buildExecutionPlan | string | Execution plan used for deployment builds. |
runtimeExecutionPlan | string | Execution plan used for SSR execution. |
buildRuntime | string | Site build runtime. |
adapter | string | Site framework adapter. |
fallbackFile | string | Fallback filename replacing the 404 page. When null, the platform default 404 page is shown. |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"siteId": "marketing-site",
"name": "Marketing Site",
"framework": "nextjs",
"buildRuntime": "node-22",
"adapter": "static",
"installCommand": "npm install",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"timeout": 15,
"logging": true
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "My Site",
"enabled": true,
"live": true,
"logging": true,
"framework": "nextjs",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"deploymentScreenshotLight": "5e5ea5c16897e",
"deploymentScreenshotDark": "5e5ea5c16897e",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
],
"timeout": 300,
"installCommand": "npm install",
"buildCommand": "npm run build",
"startCommand": "node custom-server.mjs",
"outputDirectory": "build",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "sites/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-512mb",
"runtimeSpecification": "s-1vcpu-512mb",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html"
}GET /v1/sites/{siteId}
Read the full configuration of a single site by ID, including active/latest deployment pointers and the live flag (scope sites.read. SDK: Sites.get.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
Output: 200, model site (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Site ID. |
$createdAt | string | Site creation time (ISO 8601). |
$updatedAt | string | Site update time (ISO 8601). |
name | string | Site name. |
enabled | boolean | Whether the site is enabled. |
live | boolean | Whether the site has been deployed with the latest configuration. After modifying configuration such as variables/build commands, it becomes false; redeployment is required for changes to take effect. |
logging | boolean | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
framework | string | Site framework. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
timeout | integer | Maximum request duration (seconds). |
outputDirectory | string | Directory containing the site's build artifacts. |
adapter | string | Site framework adapter. |
fallbackFile | string | Fallback filename replacing the 404 page. When null, the platform default 404 page is shown. |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_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",
"name": "My Site",
"enabled": true,
"live": true,
"logging": true,
"framework": "nextjs",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"deploymentScreenshotLight": "5e5ea5c16897e",
"deploymentScreenshotDark": "5e5ea5c16897e",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
],
"timeout": 300,
"installCommand": "npm install",
"buildCommand": "npm run build",
"startCommand": "node custom-server.mjs",
"outputDirectory": "build",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "sites/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-512mb",
"runtimeSpecification": "s-1vcpu-512mb",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html"
}PUT /v1/sites/{siteId}
Update site configuration: fields not provided keep their current values; after modifying configuration that requires redeployment, the site's live becomes false (scope sites.write. SDK: Sites.update.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | Yes | — | Site name. At most 128 characters. |
framework | body | string | Yes | analog / angular / nextjs / react / nuxt / vue / sveltekit / astro …… (see GET /sites/frameworks for the full list) | Site framework. |
enabled | body | boolean | No | — | Whether to enable the site. When disabled, it is inaccessible to users, but a Server SDK with an API Key can still access it; switching does not lose data. |
logging | body | boolean | No | — | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
timeout | body | integer | No | — | Maximum request duration (seconds). |
installCommand | body | string | No | — | Install command. |
buildCommand | body | string | No | — | Build command. |
startCommand | body | string | No | — | Custom start command. Leave empty to use the default. |
outputDirectory | body | string | No | — | Site build artifact directory. |
buildRuntime | body | string | No | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 …… (see GET /functions/runtimes for the full list) | Runtime used by the build step. |
adapter | body | string | No | static / ssr | Rendering strategy adapter: static (pure static) / ssr (server-side rendering). |
fallbackFile | body | string | No | — | Fallback file for SPA sites. |
installationId | body | string | No | — | AppBase installation ID used for VCS deployment. |
providerRepositoryId | body | string | No | — | ID of the VCS repository associated with the site. |
providerBranch | body | string | No | — | Production branch of the repository associated with the site. |
providerSilentMode | body | boolean | No | — | Whether the VCS connection for the associated repository is in silent mode. In silent mode, no comments are posted on commits and PRs. |
providerRootDirectory | body | string | No | — | Path of the site's code within the associated repository. |
buildSpecification | body | string | No | — | Build spec for the site deployment. |
runtimeSpecification | body | string | No | — | Runtime spec for SSR execution. |
buildExecutionPlan | body | string | No | Can be null | Execution plan used for the site deployment build. If omitted, the current value is kept. |
runtimeExecutionPlan | body | string | No | Can be null | Execution plan used for SSR execution. If omitted, the current value is kept. |
deploymentRetention | body | integer | No | — | Number of retention days before non-active deployments are deleted. 0 means retain all. |
siteId | path | string | Yes | — | Site ID. |
Output: 200, model site (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Site ID. |
$createdAt | string | Site creation time (ISO 8601). |
$updatedAt | string | Site update time (ISO 8601). |
name | string | Site name. |
enabled | boolean | Whether the site is enabled. |
live | boolean | Whether the site has been deployed with the latest configuration. After modifying configuration such as variables/build commands, it becomes false; redeployment is required for changes to take effect. |
logging | boolean | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
framework | string | Site framework. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
timeout | integer | Maximum request duration (seconds). |
outputDirectory | string | Directory containing the site's build artifacts. |
adapter | string | Site framework adapter. |
fallbackFile | string | Fallback filename replacing the 404 page. When null, the platform default 404 page is shown. |
Call example:
curl -X PUT "https://<your-endpoint>/v1/sites/<SITE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Site",
"framework": "nextjs",
"adapter": "static",
"installCommand": "npm install",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"timeout": 15,
"logging": true
}'Response example:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "My Site",
"enabled": true,
"live": true,
"logging": true,
"framework": "nextjs",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"deploymentScreenshotLight": "5e5ea5c16897e",
"deploymentScreenshotDark": "5e5ea5c16897e",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
],
"timeout": 300,
"installCommand": "npm install",
"buildCommand": "npm run build",
"startCommand": "node custom-server.mjs",
"outputDirectory": "build",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "sites/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-512mb",
"runtimeSpecification": "s-1vcpu-512mb",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html"
}DELETE /v1/sites/{siteId}
Delete a site by ID (its deployments and variables become unavailable as well) (scope sites.write. SDK: Sites.delete.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/sites/<SITE_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/sites/{siteId}/deployment
Cut over the site's active deployment: visitors will henceforth access the build artifacts of the newly activated deployment (scope sites.write. SDK: Sites.updateSiteDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
deploymentId | body | string | Yes | — | Deployment ID. |
siteId | path | string | Yes | — | Site ID. |
Output: 200, model site (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Site ID. |
$createdAt | string | Site creation time (ISO 8601). |
$updatedAt | string | Site update time (ISO 8601). |
name | string | Site name. |
enabled | boolean | Whether the site is enabled. |
live | boolean | Whether the site has been deployed with the latest configuration. After modifying configuration such as variables/build commands, it becomes false; redeployment is required for changes to take effect. |
logging | boolean | When disabled, request logs no longer record content and errors, and site responses are slightly faster. |
framework | string | Site framework. |
deploymentId | string | ID of the currently active deployment. |
latestDeploymentId | string | ID of the latest (not necessarily active) deployment. |
timeout | integer | Maximum request duration (seconds). |
outputDirectory | string | Directory containing the site's build artifacts. |
adapter | string | Site framework adapter. |
fallbackFile | string | Fallback filename replacing the 404 page. When null, the platform default 404 page is shown. |
Call example:
curl -X PATCH "https://<your-endpoint>/v1/sites/<SITE_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",
"name": "My Site",
"enabled": true,
"live": true,
"logging": true,
"framework": "nextjs",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"deploymentScreenshotLight": "5e5ea5c16897e",
"deploymentScreenshotDark": "5e5ea5c16897e",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
],
"timeout": 300,
"installCommand": "npm install",
"buildCommand": "npm run build",
"startCommand": "node custom-server.mjs",
"outputDirectory": "build",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "sites/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-512mb",
"runtimeSpecification": "s-1vcpu-512mb",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html"
}Deployment
GET /v1/sites/{siteId}/deployments
List all deployments of the site with pagination (scope sites.read. SDK: Deployments.listDeployments.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
queries | query | string[] | No | Default [] | Query string array, generated by the SDK's Query builder (of the form limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: buildSize, sourceSize, totalSize, buildDuration, status, activate, type. At most 100 entries, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model deploymentList: total (total number of matches, not calculated when total=false) + deployments[] (current page of data).
Key fields of the element model deployment:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -G "https://<your-endpoint>/v1/sites/<SITE_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=landing"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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments
Upload a site code package to create a new deployment (multipart/form-data); install/build commands and the artifact directory can be overridden at the deployment level. The build runs asynchronously and returns 202 (scope sites.write. SDK: Deployments.createDeployment.)
Input (multipart/form-data; file fields uploaded via -F "code=@./code.tgz")
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
installCommand | body (form) | string | No | Can be null | Install command. |
buildCommand | body (form) | string | No | Nullable null | Build command. |
outputDirectory | body (form) | string | No | May be null | output directory. |
code | body (form) | string | Yes | — | gzip-compressed code package. When using the AppBase CLI, pass the code directory path and the CLI packages it automatically; the path must be inside the current directory. |
activate | body (form) | boolean | No | — | Whether to automatically activate the deployment after the build completes. |
siteId | path | string | Yes | — | Site ID. |
Output: 202, model deployment, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
$updatedAt | string | Deployment update time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
screenshotLight | string | File ID of the light-theme screenshot. |
screenshotDark | string | File ID of the dark-theme screenshot. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildLogs | string | Build logs. |
buildDuration | integer | Current build duration (seconds). |
providerRepositoryName | string | VCS provider repository name. |
providerRepositoryOwner | string | VCS repository owner name. |
providerRepositoryUrl | string | VCS repository URL. |
providerCommitHash | string | VCS commit hash. |
providerCommitAuthorUrl | string | VCS commit author profile page. |
providerCommitAuthor | string | VCS commit author name. |
providerCommitMessage | string | Commit message. |
providerCommitUrl | string | VCS commit URL. |
providerBranch | string | VCS repository branch. |
providerBranchUrl | string | VCS repository branch. |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites/<SITE_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-F "installCommand=npm install" \
-F "buildCommand=npm run build" \
-F "outputDirectory=dist" \
-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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/duplicate
Start a new build from an existing deployment: rebuilds according to the site's current configuration (including the modified build command/output directory) without re-uploading source code (scope sites.write. SDK: Deployments.createDuplicateDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
deploymentId | body | string | Yes | — | Deployment ID. |
siteId | path | string | Yes | — | Site ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites/<SITE_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"
}'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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/template
Create a site deployment from a template repository: specify the repository, owner, directory, and reference (commit/branch/tag) (scope sites.write. SDK: Deployments.createTemplateDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
repository | body | string | Yes | — | Template repository name. |
owner | body | string | Yes | — | Template repository owner. |
rootDirectory | body | string | Yes | — | Path of the site code within the template repository. |
type | body | string | Yes | branch / commit / tag | Type of the reference: commit / branch / tag. |
reference | body | string | Yes | — | Value of the reference: commit hash, branch name, or release tag. |
activate | body | boolean | No | — | Whether to automatically activate this deployment after the build completes. |
siteId | path | string | Yes | — | Site ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites/<SITE_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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/vcs
For sites already connected to a VCS, create a deployment from a branch, commit, or tag of its repository (scope sites.write. SDK: Deployments.createVcsDeployment.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
type | body | string | Yes | branch / commit / tag | Type of the reference: branch / commit. |
reference | body | string | Yes | — | VCS reference used to create the deployment: branch name or commit hash (depending on type). |
activate | body | boolean | No | — | Whether to automatically activate this deployment after the build completes. |
siteId | path | string | Yes | — | Site ID. |
Output: 202, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites/<SITE_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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/{deploymentId}
Read a single deployment's details, used for polling build status (scope sites.read. SDK: Deployments.getDeployment.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 200, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/{deploymentId}/download
Download a deployment's source package or build artifacts; returns the attachment binary stream (scope sites.read. SDK: Deployments.getDeploymentDownload.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
type | query | string | No | source / output; default "source" | Content to download: source (source package) or output (build artifact). |
Output: 200, binary file stream (Content-Disposition: attachment attachment download; type=source is the source package, type=output is the build artifact).
Call example:
curl -G "https://<your-endpoint>/v1/sites/<SITE_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/sites/{siteId}/deployments/{deploymentId}/status
Cancel an in-progress or queued site deployment build: in-progress builds are stopped and marked canceled; builds in ready / failed states cannot be canceled (scope sites.write. SDK: Deployments.updateDeploymentStatus.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 200, model deployment (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Deployment ID. |
$createdAt | string | Deployment creation time (ISO 8601). |
type | string | Deployment type. |
resourceId | string | ID of the owning resource. |
resourceType | string | Type of the owning resource. |
entrypoint | string | Entry file used by the deployment to execute code. |
sourceSize | integer | Source package size (bytes). |
buildSize | integer | Build artifact size (bytes). |
totalSize | integer | Total size (source + build artifact, bytes). |
buildId | string | Current build ID. |
activate | boolean | Whether to automatically activate after the build completes. |
status | string | Deployment status: waiting / processing / building / ready / canceled / failed. |
buildDuration | integer | Current build duration (seconds). |
Call example:
curl -X PATCH "https://<your-endpoint>/v1/sites/<SITE_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": "marketing-site",
"resourceType": "site",
"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/sites/{siteId}/deployments/{deploymentId}
Delete the specified deployment (scope sites.write. SDK: Deployments.deleteDeployment.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
deploymentId | path | string | Yes | — | Deployment ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/sites/<SITE_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)._
SSR Logs and Runtime Status
GET /v1/sites/{siteId}/logs
List a site's SSR request logs with pagination (one execution record per request), controlled by the site's logging switch (scope log.read. SDK: Logs.listLogs.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
queries | query | string[] | No | Default [] | Query string array, generated by the SDK's Query builder (of the form limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: trigger, status, responseStatusCode, duration, requestMethod, requestPath, deploymentId. At most 100 entries, each at most 4096 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model executionList: total (total number of matches, not calculated when total=false) + executions[] (current page of data).
Key fields of the element model execution:
| Field | Type | Description |
|---|---|---|
$id | string | Execution record ID. |
$createdAt | string | Execution record creation time (ISO 8601). |
functionId | string | Function ID. |
deploymentId | string | ID of the deployment used to trigger this execution. |
trigger | string | Trigger source: http / schedule / event. |
status | string | Execution status: waiting / processing / completed / failed / scheduled. |
requestMethod | string | HTTP request method. |
requestPath | string | HTTP request path (may include the query string). |
responseStatusCode | integer | HTTP response status code. |
responseBody | string | HTTP response body returned by the function. |
logs | string | Function logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
errors | string | Function error output (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
duration | number | Execution duration of the resource (function/site) in seconds. |
Call example:
curl -G "https://<your-endpoint>/v1/sites/<SITE_ID>/logs" \
-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/sites/{siteId}/logs/{logId}
Read the full content of a single SSR request log (including status code, duration, and log/error output) (scope log.read. SDK: Logs.getLog.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
logId | path | string | Yes | — | Log ID. |
Output: 200, model execution, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Execution record ID. |
$createdAt | string | Execution record creation time (ISO 8601). |
$updatedAt | string | Execution record update time (ISO 8601). |
$permissions | string[] | Execution role. |
functionId | string | Function ID. |
deploymentId | string | ID of the deployment used to trigger this execution. |
trigger | string | Trigger source: http / schedule / event. |
status | string | Execution status: waiting / processing / completed / failed / scheduled. |
requestMethod | string | HTTP request method. |
requestPath | string | HTTP request path (may include the query string). |
requestHeaders | headers[] | HTTP request header key-value object. Only whitelisted headers are returned; executions created synchronously return all request headers. |
responseStatusCode | integer | HTTP response status code. |
responseBody | string | HTTP response body returned by the function. |
responseHeaders | headers[] | HTTP response header key-value object. Only whitelisted headers are returned; executions created synchronously return all response headers. |
logs | string | Function logs (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
errors | string | Function error output (last 4000 characters). Content is present only when called with an API Key or returned as a webhook payload; otherwise an empty string. |
duration | number | Execution duration of the resource (function/site) in seconds. |
scheduledAt | string | Scheduled execution time. If left empty, execution is queued immediately. |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_ID>/logs/<LOG_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/sites/{siteId}/logs/{logId}
Delete a single SSR request log (scope log.write. SDK: Logs.deleteLog.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
logId | path | string | Yes | — | Log ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/sites/<SITE_ID>/logs/<LOG_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/sites/{siteId}/runtime-status
Read the security status summary of the site's SSR resident runtime (scope sites.read. SDK: Sites.getRuntimeStatus.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
Output: 200, model runtimeStatus, fields:
| Field | Type | Description |
|---|---|---|
status | string | Runtime status summary. |
coverage | string | Coverage of the status data. |
updatedAt | string | Last update time of the underlying resource. |
message | string | User-facing safe status message. |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_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."
}Site variables
GET /v1/sites/{siteId}/variables
List all variables for the site (secret variable values are not returned in plaintext) (scope sites.read. SDK: Variables.listVariables.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
Output: 200, model variableList: total (total number of matches, not calculated when total=false) + variables[] (current page of data).
Key fields of the element model variable:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_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": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}
]
}POST /v1/sites/{siteId}/variables
Create site variables: injected as environment variables into builds and the SSR runtime (scope sites.write. SDK: Variables.createVariable.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
key | body | string | Yes | — | Variable key name. Up to 255 characters. |
value | body | string | Yes | — | Variable value. Up to 8192 characters. |
secret | body | boolean | No | — | Secret variables can be updated/deleted, but only the site can read them at build and runtime. |
siteId | path | string | Yes | — | Site ID. |
Output: 201, model variable, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
$createdAt | string | Variable creation time (ISO 8601). |
$updatedAt | string | Variable creation time (ISO 8601). |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl -X POST "https://<your-endpoint>/v1/sites/<SITE_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"key": "API_KEY",
"value": "myPa$$word1",
"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": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}GET /v1/sites/{siteId}/variables/{variableId}
Read a single variable by ID (secret variable values are masked) (scope sites.read. SDK: Variables.getVariable.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 200, model variable (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl "https://<your-endpoint>/v1/sites/<SITE_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": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}PUT /v1/sites/{siteId}/variables/{variableId}
Update a variable: takes effect for builds/SSR after reactivating the deployment (scope sites.write. SDK: Variables.updateVariable.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
key | body | string | Yes | — | Variable key name. Up to 255 characters. |
value | body | string | No | Can be a null | variable value. Maximum 8192 characters. |
secret | body | boolean | No | May be null | Secret variables can be updated/deleted, but only the site can read them at build and runtime. |
siteId | path | string | Yes | — | Site ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 200, model variable (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Variable ID. |
key | string | Variable key name. |
value | string | Variable value. |
secret | boolean | Whether it is a secret variable. Secret variables can only be updated or deleted, not read. |
resourceType | string | Service the variable belongs to: project / function. |
resourceId | string | ID of the resource the variable belongs to. Empty when resourceType=project; the function ID when resourceType=function. |
Call example:
curl -X PUT "https://<your-endpoint>/v1/sites/<SITE_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"key": "API_KEY",
"value": "myPa$$word1",
"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": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "site",
"resourceId": "marketing-site"
}DELETE /v1/sites/{siteId}/variables/{variableId}
Delete a specified variable (scope sites.write. SDK: Variables.deleteVariable.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
siteId | path | string | Yes | — | Site ID. |
variableId | path | string | Yes | — | Variable ID. |
Output: 204 No response body.
Call example:
curl -X DELETE "https://<your-endpoint>/v1/sites/<SITE_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)._
Enumeration Endpoints
GET /v1/sites/frameworks
List all frontend frameworks and their adapters supported by the current instance (public scope) (scope public. SDK: Frameworks.listFrameworks.)
input: Path parameters only; no query or request body.
Output: 200, model frameworkList: total (total number of matches, not calculated when total=false) + frameworks[] (current page of data).
Key fields of the element model framework:
| Field | Type | Description |
|---|---|---|
key | string | Framework key name. |
name | string | Framework name. |
buildRuntime | string | Default build runtime version. |
runtimes | string[] | List of supported runtime versions. |
adapters | frameworkAdapter[] | List of supported rendering adapters. |
Call example:
curl "https://<your-endpoint>/v1/sites/frameworks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"total": 5,
"frameworks": [
{
"key": "sveltekit",
"name": "SvelteKit",
"buildRuntime": "node-22",
"runtimes": [
"node-22"
],
"adapters": [
{
"key": "static",
"installCommand": "npm install",
"buildCommand": "npm run build",
"outputDirectory": "./dist",
"fallbackFile": "index.html"
}
]
}
]
}GET /v1/sites/specifications
List the build/SSR runtime machine specs allowed by the instance (CPU and memory tiers) (scope sites.read. SDK: Frameworks.listSpecifications.)
input: Path parameters only; no query or request body.
Output: 200, model specificationList: total (total number of matches, not calculated when total=false) + specifications[] (current page of data).
Key fields of the element model specification:
| Field | Type | Description |
|---|---|---|
memory | integer | Memory size (MB). |
cpus | number | Number of CPU cores. |
enabled | boolean | Whether this specification is enabled. |
slug | string | Specification identifier (slug). |
Call example:
curl "https://<your-endpoint>/v1/sites/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/sites/execution-plans
List the execution plans available for site builds/SSR runs; can be filtered by framework (scope sites.read. SDK: ExecutionPlans.listExecutionPlans.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
framework | query | string | No | analog / angular / nextjs / react / nuxt / vue / sveltekit / astro …… (for the full list, refer to GET /sites/frameworks) | Site framework used to filter execution plans. |
Output: 200, model executionPlanList: total (total number of matches, not calculated when total=false) + executionPlans[] (current page of data).
Key fields of the element model executionPlan:
| Field | Type | Description |
|---|---|---|
id | string | Stable execution plan ID. |
name | string | Execution plan display name. |
summary | string | Execution plan description. |
suitableFor | string | Resource type supported by this execution plan. |
recommended | boolean | Whether this is a recommended execution plan. |
availability | string | Availability of this execution plan. |
effectiveOn | string | Effective timing of the selected execution plan. |
Call example:
curl -G "https://<your-endpoint>/v1/sites/execution-plans" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "framework=nextjs"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
}
]
}Errors and boundaries
Site/deployment/variable/log not found:
404+site_not_found/deployment_not_found/variable_not_found/log_not_found; duplicate ID:409+site_already_exists.Build failure: deployment
status=failed, build output in the deployment record'sbuildLogs;PATCH .../deployments/{deploymentId}/statuscan only cancel builds that are in progress or queued (marked ascanceled) and cannot substitute for a fix.adapter=ssrrequiresruntimeSpecificationsupport and consumes runtime resources; for purely static sites usestatic+fallbackFile.frameworkvalues must come fromGET /sites/frameworks;startCommandonly takes effect in SSR contexts.Deleting a site cascades to delete all deployments and variables;
deploymentRetentionautomatic cleanup only deletes non-active deployments.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Sites.list / create / get / update / delete | /sites CRUD |
Sites.updateSiteDeployment | PATCH /sites/{siteId}/deployment |
Sites.listDeployments / createDeployment / createDuplicateDeployment / createTemplateDeployment / createVcsDeployment / getDeployment / getDeploymentDownload / updateDeploymentStatus / deleteDeployment | /sites/{siteId}/deployments* |
Sites.listLogs / getLog / deleteLog | /sites/{siteId}/logs* |
Sites.getRuntimeStatus | GET /sites/{siteId}/runtime-status |
Sites.listVariables / createVariable / getVariable / updateVariable / deleteVariable | /sites/{siteId}/variables* |
Sites.listFrameworks / listSpecifications / listExecutionPlans | /sites/frameworks、/sites/specifications、/sites/execution-plans |