Docs
Contents

Project API

The management plane for the project itself: project variables (environment variables injected at build/run time) and table mode conversion (bulk migration of database tables to a target table pool mode).

Service and resource boundaries

The Project API (/v1/project/*) provides global management capabilities for a single Agentbase project (e.g., the showcase project enterprise-ai-hub-210), covering two major subdomains:

Resources and Base Paths

Authentication and Permissions

For authentication and request header conventions, see General Conventions. Scopes in this domain: project.read / project.write.

Endpoint overview

This module contains 12 endpoints in total: the first 5 endpoints handle CRUD for project variables (/project/variables*); the remaining 7 endpoints handle target enumeration, task creation, migration launch, formal cutover, emergency rollback, and source data deletion for table mode conversion tasks (/project/table-mode-conversions*).

Endpoint List

Method + pathPurpose
GET /project/variablesList project variables
POST /project/variablesCreate project variable
GET /project/variables/{variableId}Get a variable
PUT /project/variables/{variableId}Update a variable
DELETE /project/variables/{variableId}Delete a variable
GET /project/table-mode-conversionsTable mode conversions
POST /project/table-mode-conversionsInitiate conversion
GET .../table-mode-conversions/targetsAvailable target modes/tags
GET .../table-mode-conversions/{conversionId}Conversion details
PATCH .../{conversionId}/startStart conversion
PATCH .../{conversionId}/cutoverCutover
PATCH .../{conversionId}/rollbackRollback
PATCH .../{conversionId}/source-data/deleteDelete source data

Endpoint details

Requests and Responses

The following sections give inputs, outputs, copyable call examples, and response examples for each endpoint. For authentication header and example variable conventions, see general conventions.

GET /v1/project/variables

List project-level variables. The value of secret variables is masked in the list.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Filterable fields: key, resourceType, resourceId, secret; use limit(n)/offset(n) for pagination
totalquerybooleanNoDefault truePass false to skip counting

Output: 200, returning the variableList model: total + variables[]. For the structure of the variable field, see POST /v1/project/variables.

FieldTypeDescription
totalintegerTotal number of variables matching the query
variables[]variable[]Variable objects

Call example:

curl \
  "https://<your-endpoint>/v1/project/variables?queries[]=limit(25)&total=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "variables": [
    {
      "$id": "66a9d9b804d8e",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "key": "API_KEY",
      "value": "whsec_9f8e7d6c5b4a",
      "secret": false,
      "resourceType": "project",
      "resourceId": ""
    }
  ]
}

POST /v1/project/variables

Create a project variable. Variables are injected as environment variables during Functions / Sites builds and at runtime (function-level/site-level variables with the same key override project-level ones).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
variableIdbodystringYesVariable ID: custom or pass unique(); allowed characters are a-z, A-Z, 0-9, ., -, _, up to 36 characters
keybodystringYesVariable key (environment variable name), up to 255 characters
valuebodystringYesVariable value, up to 8192 characters
secretbodybooleanNoDefault falseWhen set to true, the value is only visible to the project at build/runtime; any admin API read returns a masked value; the secret attribute cannot be switched back

Output: 201, returning the variable model. Full field table:

FieldTypeDescription
$idstringVariable ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
keystringVariable key (injected as the environment variable name)
valuestringVariable value; secret variables are masked in read endpoints
secretbooleanWhether this is a secret variable
resourceTypestringOwning service: project (project-level) or function (function-level)
resourceIdstringOwning resource ID; empty string for project-level variables

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/project/variables" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "variableId": "66a9d9b804d8e",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false
}'

Response example:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

Credentials that must be kept confidential (third-party keys, signing keys) should have secret=true set: subsequent read endpoints return a mask for value; they can only be updated or deleted, and the plaintext cannot be viewed again.

GET /v1/project/variables/{variableId}

Get a single project variable by ID (the value of secret variables is masked).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
variableIdpathstringYesVariable ID

Output: 200, returning the variable model; see fields in POST /v1/project/variables.

Call example:

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

Response example:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

PUT /v1/project/variables/{variableId}

Update a project variable's key/value/secret flag. Once created, a secret variable cannot be changed back to non-secret (and vice versa); it can only be deleted and recreated.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
variableIdpathstringYesVariable ID
keybodystringNoNew key name, up to 255 characters
valuebodystringNoNew value, up to 8192 characters
secretbodybooleanNoSecret flag (cannot be the opposite of the value at creation)

Output : 200, returns a variable model.

Call example:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/project/variables/66a9d9b804d8e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "API_KEY_V2",
  "value": "whsec_aa11bb22cc33"
}'

Response example:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY_V2",
  "value": "whsec_aa11bb22cc33",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

DELETE /v1/project/variables/{variableId}

Delete a project variable. The environment variable will disappear on the next build/runtime injection.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
variableIdpathstringYesVariable ID

Output: 204 No Content, no response body.

Call example:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/project/variables/66a9d9b804d8e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/project/table-mode-conversions

List all table mode conversion tasks for the project (history and in-progress).

Input:

No request parameters.

Output: 200, returning the projectTableModeConversionList model: total + conversions[]. For the structure of the conversion field, see POST /v1/project/table-mode-conversions.

FieldTypeDescription
totalintegerTotal number of conversion tasks
conversions[]projectTableModeConversion[]Conversion task objects

Call example:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "conversions": [
    {
      "$id": "conversion-1",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "projectId": "YOUR_PROJECT_ID",
      "sourcePool": "shared-v2",
      "sourceTableMode": "shared",
      "targetPool": "json-v2",
      "targetTableMode": "jsontable",
      "targetTag": "production",
      "status": "created",
      "progressTotal": 100,
      "progressDone": 0,
      "batchSize": 1000,
      "freezeWindowMaxSecs": 3600,
      "retentionSeconds": 2592000,
      "sourceDataDeleteAt": null,
      "sourceDataDeletedAt": null,
      "sourceDataDeleteStatus": "pending",
      "sourceDataDeleteError": null,
      "verificationReport": {},
      "errorMessage": null,
      "frozenAt": null,
      "cutoverAt": null,
      "rollbackDeadline": null
    }
  ]
}

POST /v1/project/table-mode-conversions

Initiate a table mode conversion: bulk migrate the project's database tables to a target table pool mode. After creation the task is in the created state and requires .../start to start backfill.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
targetTableModebodystringNojsontable / sharedTarget table mode
targetPoolbodystringNoTarget pool alias; if omitted, an available target pool is matched automatically
targetTagbodystringNoTarget pool tag; an empty string selects the untagged fallback pool
batchSizebodyintegerNoDefault 1000Backfill batch size
freezeWindowMaxSecsbodyintegerNoDefault 3600Upper limit of the write-freeze window during the cutover phase (seconds)
retentionSecondsbodyintegerNoDefault 2592000 (30 days)Source data retention after cutover (seconds), i.e. the rollback window

Output: 201, returning the projectTableModeConversion model. Full field table:

FieldTypeDescription
$idstringConversion task ID
$createdAt / $updatedAtstringCreation/update time (ISO 8601)
projectIdstringProject ID
sourcePool / sourceTableModestringSource pool alias and source table mode
targetPool / targetTableMode / targetTagstringTarget pool alias, target table mode (jsontable / shared), and target pool tag
statusstringState machine: created → backfill (backfill) → verifying (verification) → frozen/cutover (write freeze/cutover) → completed; on failure it is failed and may rollback
progressTotal / progressDoneintegerTotal records to migrate and number completed
batchSizeintegerBackfill batch size
freezeWindowMaxSecsintegerUpper limit of the write-freeze window (seconds)
retentionSecondsintegerSource data retention after cutover (seconds)
sourceDataDeleteAt / sourceDataDeletedAt / sourceDataDeleteStatus / sourceDataDeleteErrorstringSource data cleanup scheduled time/completion time/status/failure reason
verificationReportobjectVerification report (available after verification completes)
errorMessagestringFailure reason (when the conversion fails)
frozenAt / cutoverAt / rollbackDeadlinestringWrite freeze time/cutover time/rollback deadline (ISO 8601)

Call example:

curl \
  -X POST \
  "https://<your-endpoint>/v1/project/table-mode-conversions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000
}'

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "created",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

Before creating, you may first call GET .../targets to confirm available target modes and tags; if the target is unavailable (no matching pool/tag), creation fails immediately.

GET /v1/project/table-mode-conversions/targets

List currently available target table modes and pool tags as the basis for selection before initiating a conversion.

Input:

No request parameters.

Output : 200, returns a projectTableModeConversionTargetPoolList model.

FieldTypeDescription
sourcePool / sourceTableModestringCurrent source pool alias and source table mode
targetModes[]object[]Each target mode and selectable tags: tableMode, label, supported (whether the source mode supports migrating to that mode), available (whether a selectable pool exists), totalPools, tags[] (each item contains tag, name, label, poolCount)
totalintegerTotal number of target pools
pools[]object[]Target pool details: alias, status, region, tableMode, tags[], projectCount

Call example:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions/targets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetModes": [
    {
      "tableMode": "jsontable",
      "label": "JSON table",
      "supported": true,
      "available": true,
      "totalPools": 2,
      "tags": [
        {
          "tag": "production",
          "name": "production",
          "label": "Production",
          "poolCount": 1
        },
        {
          "tag": "",
          "name": "no-tag",
          "label": "No tag",
          "poolCount": 1
        }
      ]
    }
  ],
  "total": 2,
  "pools": [
    {
      "alias": "json-v2",
      "status": "active",
      "region": "cn-hangzhou",
      "tableMode": "jsontable",
      "tags": [
        "production"
      ],
      "projectCount": 5
    }
  ]
}

GET /v1/project/table-mode-conversions/{conversionId}

Get conversion task details: status, backfill progress, and timestamps for each phase. Poll this endpoint to track task progress.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
conversionIdpathstringYesConversion task ID

Output: 200, returning the projectTableModeConversion model; fields are described in POST /v1/project/table-mode-conversions. When status is backfill, watch progressDone/progressTotal.

Call example:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "backfill",
  "progressTotal": 100,
  "progressDone": 25,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/start

Start the conversion: begin backfilling source data into the target pool (status created → backfill). Repeating start on an in-progress task returns a conflict.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
conversionIdpathstringYesConversion task ID

Output: 200, returning projectTableModeConversion (status becomes backfill).

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/start" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "backfill",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/cutover

Perform the cutover: briefly freeze writes, verify, then switch traffic to the target pool. By default the cutover is refused when verification fails; force=true allows forcing the cutover and skipping verification (the rollback window is still preserved).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
conversionIdpathstringYesConversion task ID
forcebodybooleanNoDefault falseForce the cutover even if verification fails

Output: 200, returning projectTableModeConversion (status enters cutover/completed; cutoverAt and rollbackDeadline are populated).

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/cutover" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "force": false
}'

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "completed",
  "progressTotal": 100,
  "progressDone": 100,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": "2020-10-15T06:38:00.000+00:00",
  "cutoverAt": "2020-10-15T06:38:00.000+00:00",
  "rollbackDeadline": "2020-10-15T06:38:00.000+00:00"
}

PATCH /v1/project/table-mode-conversions/{conversionId}/rollback

Roll back to the source pool. Only valid within rollbackDeadline (determined by retentionSeconds); a rollback outside the state machine returns a conflict.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
conversionIdpathstringYesConversion task ID

Output: 200, returning projectTableModeConversion (the status returns to the rollback-related state machine node).

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/rollback" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "rollback",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/source-data/delete

Delete the source data of a completed cutover task. Only valid for conversions that have completed cutover; after deletion, rollback is no longer possible — this is an irreversible operation.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
conversionIdpathstringYesConversion task ID

Output: 200, returning projectTableModeConversion (sourceDataDeleteStatus advances from pending; on completion sourceDataDeletedAt is populated).

Call example:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/source-data/delete" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "completed",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": "2020-10-15T06:38:00.000+00:00",
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
Project.listVariables / createVariable / getVariable / updateVariable / deleteVariable/project/variables*
Project.listProjectTableModeConversions / createProjectTableModeConversion / listProjectTableModeConversionTargets / getProjectTableModeConversion/project/table-mode-conversions*
Project.startProjectTableModeConversion / cutoverProjectTableModeConversion / rollbackProjectTableModeConversion / deleteProjectTableModeConversionSourceData.../{conversionId}/start、cutover、rollback、source-data/delete