Docs
文档目录

站点 API

站点全生命周期接口:创建站点(多前端框架,static/SSR 双渲染策略)、代码/模板/VCS 部署、构建与运行状态、SSR 运行日志、站点变量。与 functions 的部署/执行接口形态同构。

服务与资源边界

站点 API(/v1/sites/*)提供现代 Web 前端与全栈应用(Next.js、Nuxt、SvelteKit、Astro、Remix、React/Vue SPA 及静态站点)的构建、托管与服务端渲染(SSR)管理能力:支持代码压缩包上传、官方模板初始化与 Git VCS 自动构建,内置部署版本原子切换、SSR 运行时副本监控、站点级环境变量以及边缘访问请求日志审计。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:sites.read / sites.write(站点、部署、变量、规格)、log.read / log.write(请求日志)、public(框架列表)。

端点总览

Sites 模块共提供 27 个端点,涵盖:站点 CRUD 与当前激活部署切换(6 个)、部署构建包管理与产物下载(9 个)、SSR 请求日志查询与清理(3 个)、运行时状态与站点环境变量管理(6 个)以及支持的前端框架、构建规格与执行计划枚举(3 个)。

端点清单

方法 + 路径用途
GET /sites列出站点
POST /sites创建站点
GET /sites/{siteId}获取站点
PUT /sites/{siteId}更新站点配置
DELETE /sites/{siteId}删除站点
PATCH /sites/{siteId}/deployment切换激活部署
GET /sites/{siteId}/deployments列出部署
POST /sites/{siteId}/deployments上传代码创建部署
POST /sites/{siteId}/deployments/duplicate复制既有部署
POST /sites/{siteId}/deployments/template从模板创建部署
POST /sites/{siteId}/deployments/vcs从 VCS 分支/提交创建部署
GET /sites/{siteId}/deployments/{deploymentId}获取部署
GET /sites/{siteId}/deployments/{deploymentId}/download下载部署产物
PATCH /sites/{siteId}/deployments/{deploymentId}/status手动标记部署状态
DELETE /sites/{siteId}/deployments/{deploymentId}删除部署
GET /sites/{siteId}/logsSSR 请求日志列表
GET /sites/{siteId}/logs/{logId}获取单条日志
DELETE /sites/{siteId}/logs/{logId}删除日志
GET /sites/{siteId}/runtime-statusSSR 运行时状态
GET /sites/{siteId}/variables列出站点变量
POST /sites/{siteId}/variables创建变量
GET /sites/{siteId}/variables/{variableId}获取变量
PUT /sites/{siteId}/variables/{variableId}更新变量
DELETE /sites/{siteId}/variables/{variableId}删除变量
GET /sites/frameworks列出支持框架(public)
GET /sites/specifications列出构建/运行规格
GET /sites/execution-plans列出执行计划

端点详解

站点部署(POST /v1/sites/{siteId}/deployments*)采用异步构建流水线,上传代码后返回 waiting / building 状态的 deployment 对象;当传入 activate=true 时,构建一旦进入 ready 终态即自动切换为该站点的线上生产版本,无需二次调用 PATCH /v1/sites/{siteId}/deployment。

请求与响应

以下按端点逐个给出输入/输出规格、可复制的 curl 调用示例与响应示例。路径前缀 /v1;请求头 X-Appwrite-Project: <YOUR_PROJECT_ID> 与 X-Appwrite-Key: <YOUR_API_KEY> 对全部端点一致,示例中不再逐条解释。

站点 CRUD

GET /v1/sites

分页列出项目内全部站点,支持按名称、框架、启用状态等属性过滤与关键词搜索(scope sites.read。SDK:Sites.list。)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、enabled、framework、deploymentId、buildCommand、installCommand、outputDirectory、installationId。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 siteList:total(匹配总数,total=false 时不计算)+ sites[](当前页数据)。

元素模型 site 关键字段:

字段类型说明
$idstring站点 ID。
$createdAtstring站点创建时间(ISO 8601)。
$updatedAtstring站点更新时间(ISO 8601)。
namestring站点名称。
enabledboolean站点是否启用。
liveboolean站点是否已按最新配置部署。修改变量/构建命令等配置后变为 false,需重新部署生效。
loggingboolean关闭后请求日志不再记录内容与错误,站点响应略快。
frameworkstring站点框架。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
timeoutinteger最大请求时长(秒)。
outputDirectorystring站点构建产物所在目录。
adapterstring站点框架适配器。
fallbackFilestring替代 404 页面的回退文件名。为 null 时显示平台默认 404 页。

调用示例:

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"

响应示例:

{
  "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": "APP_ENV",
          "value": "development",
          "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

创建站点:选择前端框架与渲染策略(static/ssr)、构建/启动命令、构建/SSR 规格与执行计划(scope sites.write。SDK:Sites.create。)

输入(application/json)

参数位置类型必填默认/枚举说明
siteIdbodystring是—站点 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—站点名称。最长 128 字符。
frameworkbodystring是analog / angular / nextjs / react / nuxt / vue / sveltekit / astro ……(全量以 GET /sites/frameworks 为准)站点框架。
enabledbodyboolean否—是否启用站点。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbodyboolean否—关闭后请求日志不再记录内容与错误,站点响应略快。
timeoutbodyinteger否—最大请求时长(秒)。
installCommandbodystring否—安装命令。
buildCommandbodystring否—构建命令。
startCommandbodystring否—自定义启动命令。留空使用默认值。
outputDirectorybodystring否—站点构建产物目录。
buildRuntimebodystring是node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 ……(全量以 GET /functions/runtimes 为准)构建步骤使用的运行时。
adapterbodystring否static / ssr渲染策略适配器:static(纯静态)/ ssr(服务端渲染)。
installationIdbodystring否—用于 VCS 部署的 AppBase 安装 ID。
fallbackFilebodystring否—SPA 站点的回退文件。
providerRepositoryIdbodystring否—站点关联的 VCS 仓库 ID。
providerBranchbodystring否—站点关联仓库的生产分支。
providerSilentModebodyboolean否—站点关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。
providerRootDirectorybodystring否—站点代码在关联仓库中的路径。
buildSpecificationbodystring否—站点部署的构建规格。
runtimeSpecificationbodystring否—SSR 执行使用的运行规格。
buildExecutionPlanbodystring否可为 null站点部署构建使用的执行计划。省略使用遗留默认值。
runtimeExecutionPlanbodystring否可为 nullSSR 执行使用的执行计划。省略使用遗留默认值。
deploymentRetentionbodyinteger否—非激活部署删除前的保留天数。0 表示全部保留。

输出:201,模型 site,字段:

字段类型说明
$idstring站点 ID。
$createdAtstring站点创建时间(ISO 8601)。
$updatedAtstring站点更新时间(ISO 8601)。
namestring站点名称。
enabledboolean站点是否启用。
liveboolean站点是否已按最新配置部署。修改变量/构建命令等配置后变为 false,需重新部署生效。
loggingboolean关闭后请求日志不再记录内容与错误,站点响应略快。
frameworkstring站点框架。
deploymentRetentioninteger非激活部署保留天数,到期后自动删除。
deploymentIdstring当前激活的部署 ID。
deploymentCreatedAtstring激活部署的创建时间(ISO 8601)。
deploymentScreenshotLightstring激活部署的浅色主题截图文件 ID。
deploymentScreenshotDarkstring激活部署的深色主题截图文件 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentCreatedAtstring最新部署的创建时间(ISO 8601)。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
varsvariable[]站点变量列表。
timeoutinteger最大请求时长(秒)。
installCommandstring安装站点依赖的命令。
buildCommandstring构建站点的命令。
startCommandstring启动站点运行时的自定义命令。
outputDirectorystring站点构建产物所在目录。
installationIdstring站点关联的 VCS 安装 ID。
providerRepositoryIdstringVCS(版本控制系统)仓库 ID。
providerBranchstringVCS(版本控制系统)分支名。
providerRootDirectorystring站点代码在 VCS 仓库中的路径。
providerSilentModebooleanVCS 连接是否为静默模式。静默模式下不会在仓库的 PR / MR 上发表评论。
buildSpecificationstring构建使用的机器规格(CPU/内存档位)。
runtimeSpecificationstringSSR 运行使用的机器规格(CPU/内存档位)。
buildExecutionPlanstring部署构建使用的执行计划。
runtimeExecutionPlanstringSSR 执行使用的执行计划。
buildRuntimestring站点构建运行时。
adapterstring站点框架适配器。
fallbackFilestring替代 404 页面的回退文件名。为 null 时显示平台默认 404 页。

调用示例:

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
}'

响应示例:

{
  "$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": "APP_ENV",
      "value": "development",
      "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}

按 ID 读取单个站点的完整配置,含激活/最新部署指针与 live 标记(scope sites.read。SDK:Sites.get。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。

输出:200,模型 site(完整字段见前文),关键字段:

字段类型说明
$idstring站点 ID。
$createdAtstring站点创建时间(ISO 8601)。
$updatedAtstring站点更新时间(ISO 8601)。
namestring站点名称。
enabledboolean站点是否启用。
liveboolean站点是否已按最新配置部署。修改变量/构建命令等配置后变为 false,需重新部署生效。
loggingboolean关闭后请求日志不再记录内容与错误,站点响应略快。
frameworkstring站点框架。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
timeoutinteger最大请求时长(秒)。
outputDirectorystring站点构建产物所在目录。
adapterstring站点框架适配器。
fallbackFilestring替代 404 页面的回退文件名。为 null 时显示平台默认 404 页。

调用示例:

curl "https://<your-endpoint>/v1/sites/<SITE_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$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": "APP_ENV",
      "value": "development",
      "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}

更新站点配置(scope sites.write;SDK:Sites.update)。部分未传字段会采用默认值并写回,例如 enabled 可能恢复为 true,startCommand 和版本库关联字段可能被清空;更新前请读取当前配置(scope sites.read),并显式提交需要保留的设置。执行计划等字段的省略行为见下表。修改配置可能需要重新部署。

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring是—站点名称。最长 128 字符。
frameworkbodystring是analog / angular / nextjs / react / nuxt / vue / sveltekit / astro ……(全量以 GET /sites/frameworks 为准)站点框架。
enabledbodyboolean否true是否启用站点。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbodyboolean否true关闭后请求日志不再记录内容与错误,站点响应略快。
timeoutbodyinteger否30最大请求时长(秒)。
installCommandbodystring否""安装命令。
buildCommandbodystring否""构建命令。
startCommandbodystring否""自定义启动命令。留空使用默认值。
outputDirectorybodystring否""站点构建产物目录。
buildRuntimebodystring否node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 ……(全量以 GET /functions/runtimes 为准);""构建步骤使用的运行时。
adapterbodystring否static / ssr;""渲染策略适配器:static(纯静态)/ ssr(服务端渲染)。
fallbackFilebodystring否""SPA 站点的回退文件。
installationIdbodystring否""用于 VCS 部署的 AppBase 安装 ID。
providerRepositoryIdbodystring否""站点关联的 VCS 仓库 ID。
providerBranchbodystring否""站点关联仓库的生产分支。
providerSilentModebodyboolean否false站点关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。
providerRootDirectorybodystring否""站点代码在关联仓库中的路径。
buildSpecificationbodystring否按套餐默认站点部署的构建规格。
runtimeSpecificationbodystring否按套餐默认SSR 执行使用的运行规格。
buildExecutionPlanbodystring否省略保留现值站点部署构建使用的执行计划。省略保持现值。
runtimeExecutionPlanbodystring否省略保留现值SSR 执行使用的执行计划。省略保持现值。
deploymentRetentionbodyinteger否0非激活部署删除前的保留天数。0 表示全部保留。
siteIdpathstring是—站点 ID。

输出:200,模型 site(完整字段见前文),关键字段:

字段类型说明
$idstring站点 ID。
$createdAtstring站点创建时间(ISO 8601)。
$updatedAtstring站点更新时间(ISO 8601)。
namestring站点名称。
enabledboolean站点是否启用。
liveboolean站点是否已按最新配置部署。修改变量/构建命令等配置后变为 false,需重新部署生效。
loggingboolean关闭后请求日志不再记录内容与错误,站点响应略快。
frameworkstring站点框架。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
timeoutinteger最大请求时长(秒)。
outputDirectorystring站点构建产物所在目录。
adapterstring站点框架适配器。
fallbackFilestring替代 404 页面的回退文件名。为 null 时显示平台默认 404 页。

调用说明:先查询当前配置,核对更新接口各字段的默认值,再提交需要保留的字段。不要直接使用只包含部分字段的更新请求。

响应示例:

{
  "$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": "APP_ENV",
      "value": "development",
      "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}

按 ID 删除站点(其部署与变量一并不可用)(scope sites.write。SDK:Sites.delete。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。

输出:204 无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/sites/<SITE_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

_二进制流或无响应体(见输出说明)。_

PATCH /v1/sites/{siteId}/deployment

切换站点的激活部署:访客此后访问的是新激活部署的构建产物(scope sites.write。SDK:Sites.updateSiteDeployment。)

输入(application/json)

参数位置类型必填默认/枚举说明
deploymentIdbodystring是—部署 ID。
siteIdpathstring是—站点 ID。

输出:200,模型 site(完整字段见前文),关键字段:

字段类型说明
$idstring站点 ID。
$createdAtstring站点创建时间(ISO 8601)。
$updatedAtstring站点更新时间(ISO 8601)。
namestring站点名称。
enabledboolean站点是否启用。
liveboolean站点是否已按最新配置部署。修改变量/构建命令等配置后变为 false,需重新部署生效。
loggingboolean关闭后请求日志不再记录内容与错误,站点响应略快。
frameworkstring站点框架。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
timeoutinteger最大请求时长(秒)。
outputDirectorystring站点构建产物所在目录。
adapterstring站点框架适配器。
fallbackFilestring替代 404 页面的回退文件名。为 null 时显示平台默认 404 页。

调用示例:

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"
}'

响应示例:

{
  "$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": "APP_ENV",
      "value": "development",
      "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}/deployments

分页列出该站点的全部部署(scope sites.read。SDK:Deployments.listDeployments。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:buildSize、sourceSize、totalSize、buildDuration、status、activate、type。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 deploymentList:total(匹配总数,total=false 时不计算)+ deployments[](当前页数据)。

元素模型 deployment 关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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"

响应示例:

{
  "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

上传站点代码包创建新部署(multipart/form-data),可在部署级覆盖安装/构建命令与产物目录;构建异步进行,返回 202(scope sites.write。SDK:Deployments.createDeployment。)

输入(multipart/form-data,文件字段用 -F "code=@./code.tgz" 上传)

参数位置类型必填默认/枚举说明
installCommandbody(表单)string否可为 null安装命令。
buildCommandbody(表单)string否可为 null构建命令。
outputDirectorybody(表单)string否可为 null产物目录。
codebody(表单)string是—gzip 压缩的代码包。使用 AppBase CLI 时传代码目录路径,CLI 会自动打包;路径须位于当前目录内。
activatebody(表单)boolean否—构建完成后是否自动激活该部署。
siteIdpathstring是—站点 ID。

输出:202,模型 deployment,字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
$updatedAtstring部署更新时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
screenshotLightstring浅色主题截图的文件 ID。
screenshotDarkstring深色主题截图的文件 ID。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildLogsstring构建日志。
buildDurationinteger当前构建耗时(秒)。
providerRepositoryNamestringVCS 提供商仓库名。
providerRepositoryOwnerstringVCS 仓库属主名。
providerRepositoryUrlstringVCS 仓库地址。
providerCommitHashstringVCS 提交哈希。
providerCommitAuthorUrlstringVCS 提交作者主页。
providerCommitAuthorstringVCS 提交作者名。
providerCommitMessagestring提交信息。
providerCommitUrlstringVCS 提交地址。
providerBranchstringVCS 仓库分支。
providerBranchUrlstringVCS 仓库分支。

调用示例:

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"

响应示例:

{
  "$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

基于既有部署发起新构建:按站点当前配置(含修改后的构建命令/产物目录)重新构建,不重复上传源码(scope sites.write。SDK:Deployments.createDuplicateDeployment。)

输入(application/json)

参数位置类型必填默认/枚举说明
deploymentIdbodystring是—部署 ID。
siteIdpathstring是—站点 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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"
}'

响应示例:

{
  "$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

从模板仓库创建站点部署:指定仓库、属主、目录与引用(commit/branch/tag)(scope sites.write。SDK:Deployments.createTemplateDeployment。)

输入(application/json)

参数位置类型必填默认/枚举说明
repositorybodystring是—模板仓库名。
ownerbodystring是—模板仓库属主。
rootDirectorybodystring是—站点代码在模板仓库中的路径。
typebodystring是branch / commit / tagreference 的类型:commit / branch / tag。
referencebodystring是—reference 的值:提交哈希、分支名或发布标签。
activatebodyboolean否—构建完成后是否自动激活该部署。
siteIdpathstring是—站点 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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
}'

响应示例:

{
  "$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

对已关联 VCS 的站点,从其仓库的分支、提交或标签创建部署(scope sites.write。SDK:Deployments.createVcsDeployment。)

输入(application/json)

参数位置类型必填默认/枚举说明
typebodystring是branch / commit / tagreference 的类型:branch / commit。
referencebodystring是—创建部署的 VCS 引用:分支名或提交哈希(随 type 而定)。
activatebodyboolean否—构建完成后是否自动激活该部署。
siteIdpathstring是—站点 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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
}'

响应示例:

{
  "$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}

读取单个部署详情,用于轮询构建状态(scope sites.read。SDK:Deployments.getDeployment。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
deploymentIdpathstring是—部署 ID。

输出:200,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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

响应示例:

{
  "$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

下载部署的源码包或构建产物,返回附件二进制流(scope sites.read。SDK:Deployments.getDeploymentDownload。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
deploymentIdpathstring是—部署 ID。
typequerystring否source / output;默认 "source"下载内容:source(源码包)或 output(构建产物)。

输出:200,二进制文件流(Content-Disposition: attachment 附件下载;type=source 为源码包,type=output 为构建产物)。

调用示例:

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"

响应示例:

_二进制流或无响应体(见输出说明)。_

PATCH /v1/sites/{siteId}/deployments/{deploymentId}/status

取消进行中或排队中的站点部署构建:进行中的构建被停止、标记 canceled;ready / failed 的构建不可取消(scope sites.write。SDK:Deployments.updateDeploymentStatus。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
deploymentIdpathstring是—部署 ID。

输出:200,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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

响应示例:

{
  "$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}

删除指定部署(scope sites.write。SDK:Deployments.deleteDeployment。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
deploymentIdpathstring是—部署 ID。

输出:204 无响应体。

调用示例:

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

响应示例:

_二进制流或无响应体(见输出说明)。_

SSR 日志与运行状态

GET /v1/sites/{siteId}/logs

分页列出站点的 SSR 请求日志(每次请求一条 execution 记录),受站点 logging 开关控制(scope log.read。SDK:Logs.listLogs。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:trigger、status、responseStatusCode、duration、requestMethod、requestPath、deploymentId。最多 100 条、每条最长 4096 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 executionList:total(匹配总数,total=false 时不计算)+ executions[](当前页数据)。

元素模型 execution 关键字段:

字段类型说明
$idstring执行记录 ID。
$createdAtstring执行记录创建时间(ISO 8601)。
functionIdstring函数 ID。
deploymentIdstring触发本次执行使用的部署 ID。
triggerstring触发来源:http / schedule / event。
statusstring执行状态:waiting / processing / completed / failed / scheduled。
requestMethodstringHTTP 请求方法。
requestPathstringHTTP 请求路径(可含查询串)。
responseStatusCodeintegerHTTP 响应状态码。
responseBodystring函数返回的 HTTP 响应体。
logsstring函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
errorsstring函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
durationnumber资源(函数/站点)执行耗时(秒)。

调用示例:

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)"

响应示例:

{
  "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}

读取单条 SSR 请求日志的完整内容(含状态码、耗时与日志/错误输出)(scope log.read。SDK:Logs.getLog。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
logIdpathstring是—日志 ID。

输出:200,模型 execution,字段:

字段类型说明
$idstring执行记录 ID。
$createdAtstring执行记录创建时间(ISO 8601)。
$updatedAtstring执行记录更新时间(ISO 8601)。
$permissionsstring[]执行角色。
functionIdstring函数 ID。
deploymentIdstring触发本次执行使用的部署 ID。
triggerstring触发来源:http / schedule / event。
statusstring执行状态:waiting / processing / completed / failed / scheduled。
requestMethodstringHTTP 请求方法。
requestPathstringHTTP 请求路径(可含查询串)。
requestHeadersheaders[]HTTP 请求头键值对象。仅返回白名单内的头;同步创建的执行返回全部请求头。
responseStatusCodeintegerHTTP 响应状态码。
responseBodystring函数返回的 HTTP 响应体。
responseHeadersheaders[]HTTP 响应头键值对象。仅返回白名单内的头;同步创建的执行返回全部响应头。
logsstring函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
errorsstring函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
durationnumber资源(函数/站点)执行耗时(秒)。
scheduledAtstring定时执行时间。留空则立即排队执行。

调用示例:

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

响应示例:

{
  "$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}

删除单条 SSR 请求日志(scope log.write。SDK:Logs.deleteLog。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
logIdpathstring是—日志 ID。

输出:204 无响应体。

调用示例:

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

响应示例:

_二进制流或无响应体(见输出说明)。_

GET /v1/sites/{siteId}/runtime-status

读取站点 SSR 常驻运行时的安全状态摘要(scope sites.read。SDK:Sites.getRuntimeStatus。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。

输出:200,模型 runtimeStatus,字段:

字段类型说明
statusstring运行时状态摘要。
coveragestring状态数据覆盖范围。
updatedAtstring底层资源最近更新时间。
messagestring面向用户的安全状态消息。

调用示例:

curl "https://<your-endpoint>/v1/sites/<SITE_ID>/runtime-status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "status": "healthy",
  "coverage": "configuration-only",
  "updatedAt": "2026-07-12T00:00:00.000+00:00",
  "message": "All runtime replicas are healthy."
}

站点变量

GET /v1/sites/{siteId}/variables

列出该站点的全部变量(机密变量的值不回显明文)(scope sites.read。SDK:Variables.listVariables。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。

输出:200,模型 variableList:total(匹配总数,total=false 时不计算)+ variables[](当前页数据)。

元素模型 variable 关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。

调用示例:

curl "https://<your-endpoint>/v1/sites/<SITE_ID>/variables" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "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": "site",
      "resourceId": "marketing-site"
    }
  ]
}

POST /v1/sites/{siteId}/variables

创建站点变量:构建与 SSR 运行时以环境变量形式注入(scope sites.write。SDK:Variables.createVariable。)

输入(application/json)

参数位置类型必填默认/枚举说明
keybodystring是—变量键名。最长 255 字符。
valuebodystring是—变量值。最长 8192 字符。
secretbodyboolean否—机密变量可更新/删除,但只有站点可在构建与运行时读取。
siteIdpathstring是—站点 ID。

输出:201,模型 variable,字段:

字段类型说明
$idstring变量 ID。
$createdAtstring变量创建时间(ISO 8601)。
$updatedAtstring变量创建时间(ISO 8601)。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。

调用示例:

(
  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/sites/<SITE_ID>/variables" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "APP_ENV",
  "value": "development",
  "secret": false
}'
)

响应示例:

{
  "$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": "site",
  "resourceId": "marketing-site"
}

GET /v1/sites/{siteId}/variables/{variableId}

按 ID 读取单个变量(机密变量值被掩码)(scope sites.read。SDK:Variables.getVariable。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
variableIdpathstring是—变量 ID。

输出:200,模型 variable(完整字段见前文),关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。

调用示例:

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

响应示例:

{
  "$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": "site",
  "resourceId": "marketing-site"
}

PUT /v1/sites/{siteId}/variables/{variableId}

更新变量:重新激活部署后对构建/SSR 生效(scope sites.write。SDK:Variables.updateVariable。)

输入(application/json)

参数位置类型必填默认/枚举说明
keybodystring是—变量键名。最长 255 字符。
valuebodystring否可为 null变量值。最长 8192 字符。
secretbodyboolean否可为 null机密变量可更新/删除,但只有站点可在构建与运行时读取。
siteIdpathstring是—站点 ID。
variableIdpathstring是—变量 ID。

输出:200,模型 variable(完整字段见前文),关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。

调用示例:

(
  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/sites/<SITE_ID>/variables/<VARIABLE_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "APP_ENV",
  "value": "development",
  "secret": false
}'
)

响应示例:

{
  "$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": "site",
  "resourceId": "marketing-site"
}

DELETE /v1/sites/{siteId}/variables/{variableId}

删除指定变量(scope sites.write。SDK:Variables.deleteVariable。)

输入

参数位置类型必填默认/枚举说明
siteIdpathstring是—站点 ID。
variableIdpathstring是—变量 ID。

输出:204 无响应体。

调用示例:

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

响应示例:

_二进制流或无响应体(见输出说明)。_

枚举端点

GET /v1/sites/frameworks

列出当前实例支持的全部前端框架及其适配器(public scope)(scope public。SDK:Frameworks.listFrameworks。)

输入:仅路径参数,无查询与请求体。

输出:200,模型 frameworkList:total(匹配总数,total=false 时不计算)+ frameworks[](当前页数据)。

元素模型 framework 关键字段:

字段类型说明
keystring框架键名。
namestring框架名称。
buildRuntimestring默认构建运行时版本。
runtimesstring[]支持的运行时版本列表。
adaptersframeworkAdapter[]支持的渲染适配器列表。

调用示例:

curl "https://<your-endpoint>/v1/sites/frameworks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "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

列出实例允许的构建/SSR 运行机器规格(CPU 与内存档位)(scope sites.read。SDK:Frameworks.listSpecifications。)

输入:仅路径参数,无查询与请求体。

输出:200,模型 specificationList:total(匹配总数,total=false 时不计算)+ specifications[](当前页数据)。

元素模型 specification 关键字段:

字段类型说明
memoryinteger内存大小(MB)。
cpusnumberCPU 核数。
enabledboolean该规格是否启用。
slugstring规格标识(slug)。

调用示例:

curl "https://<your-endpoint>/v1/sites/specifications" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 5,
  "specifications": [
    {
      "memory": 512,
      "cpus": 1,
      "enabled": true,
      "slug": "s-1vcpu-512mb"
    }
  ]
}

GET /v1/sites/execution-plans

列出站点构建/SSR 运行可用的执行计划,可按框架过滤(scope sites.read。SDK:ExecutionPlans.listExecutionPlans。)

输入

参数位置类型必填默认/枚举说明
frameworkquerystring否analog / angular / nextjs / react / nuxt / vue / sveltekit / astro ……(全量以 GET /sites/frameworks 为准)用于过滤执行计划的站点框架。

输出:200,模型 executionPlanList:total(匹配总数,total=false 时不计算)+ executionPlans[](当前页数据)。

元素模型 executionPlan 关键字段:

字段类型说明
idstring稳定的执行计划 ID。
namestring执行计划展示名。
summarystring执行计划简述。
suitableForstring该执行计划支持的资源类型。
recommendedboolean是否为推荐执行计划。
availabilitystring该执行计划的可用性。
effectiveOnstring所选执行计划的生效时机。

调用示例:

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"

响应示例:

{
  "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
    }
  ]
}

错误与边界

与 Server SDK 的对应

service.method端点
Sites.list / create / get / update / delete/sites CRUD
Sites.updateSiteDeploymentPATCH /sites/{siteId}/deployment
Sites.listDeployments / createDeployment / createDuplicateDeployment / createTemplateDeployment / createVcsDeployment / getDeployment / getDeploymentDownload / updateDeploymentStatus / deleteDeployment/sites/{siteId}/deployments*
Sites.listLogs / getLog / deleteLog/sites/{siteId}/logs*
Sites.getRuntimeStatusGET /sites/{siteId}/runtime-status
Sites.listVariables / createVariable / getVariable / updateVariable / deleteVariable/sites/{siteId}/variables*
Sites.listFrameworks / listSpecifications / listExecutionPlans/sites/frameworks、/sites/specifications、/sites/execution-plans