Docs
Contents

Health Check API

Health probing for the instance and its subsystems: HTTP service overview, component status, storage status, queue backlog, and platform clock (server/operations perspective).

Service and resource boundaries

The Health API provides read-only instance-level and component-level probe interfaces for platform operations and automated inspection systems, covering HTTP entry liveness, underlying OceanBase database connectivity, in-memory cache, Pub/Sub, object storage, ClamAV antivirus, domain TLS certificate validity, system clock drift, and backlog and failed-task threshold monitoring for 14 categories of background async worker queues.

Resources and Base Paths

Authentication and Permissions

See general conventions for authentication and request header conventions.

Endpoint overview

The endpoints of this module are divided into four groups by probe target: core component probes (/health, /health/db, /health/cache, /health/pubsub, /health/storage*, /health/anti-virus), security and clock probes (/health/certificate, /health/time), worker queue pending backlog probes (/health/queue/{name}), and dead-letter/failed-task threshold probes (/health/queue/failed/{name}).

Endpoint List

Method + pathPurpose
GET /healthHTTP service status
GET /health/anti-virus / cache / certificate / db / pubsubComponent status
GET /health/storage / GET /health/storage/localStorage status
GET /health/queue/{name} series (audits / builds / certificates / databases / deletes / functions / logs / mails / messaging / migrations / stats-resources / stats-usage / webhooks)Queue backlog status
GET /health/timePlatform clock (Unix seconds, used for clock drift detection)
GET /health/queue/failed/{name}Failed queue threshold check

Endpoint details

The queue monitoring endpoints (/health/queue/* and /health/queue/failed/*) both support the optional threshold query parameter (default 5000): when the current backlog or failed count size is below the threshold, 200 OK is returned; when the threshold is reached or exceeded, an alert state is triggered, making it easy to integrate directly with Prometheus Blackbox Exporter or an external alerting gateway.

Requests and Responses

Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), call examples (copyable curl) and response examples. Endpoints marked with "generalized schema any" return the JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for specific fields.

Health

GET /v1/health

Probes whether the HTTP service entry is alive: the most basic health check, suitable for load balancers and liveness probes.

Input: no path/query/body parameters.

Output: Returns healthStatus:

FieldTypeDescription
namestringService name
pingintegerHealth check duration (milliseconds)
statusstringpass / fail

Call example:

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

Response example:

{
  "name": "database",
  "ping": 128,
  "status": "pass"
}

GET /v1/health/anti-virus

Probes the antivirus service connectivity and version.

Input: no path/query/body parameters.

Output: Returns healthAntivirus:

FieldTypeDescription
versionstringAntivirus service version
statusstringdisabled / offline / online

Call example:

curl "https://<your-endpoint>/v1/health/anti-virus" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "version": "1.0.0",
  "status": "online"
}

GET /v1/health/cache

Probes the in-memory cache service status (multi-node returns a list).

Input: no path/query/body parameters.

Output: Returns healthStatusList (total + statuses[], with elements of healthStatus: name / ping / status (pass / fail)).

Call example:

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

Response example:

{
  "total": 2,
  "statuses": [
    {
      "name": "cache-1",
      "ping": 2,
      "status": "pass"
    },
    {
      "name": "cache-2",
      "ping": 3,
      "status": "pass"
    }
  ]
}

GET /v1/health/certificate

Validates the TLS certificate of the specified domain: returns the certificate subject, issuer, and validity period.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
domainquerystringNo—The domain to validate; defaults to the platform's own domain.

Output: Returns healthCertificate:

FieldTypeDescription
namestringCertificate name (e.g., /CN=www.google.com)
subjectSNstringSubject SN
issuerOrganisationstringIssuing authority
validFromstringValid from (Unix seconds)
validTostringValid until (Unix seconds)
signatureTypeSNstringSignature algorithm (e.g., RSA-SHA256)

Call example:

curl "https://<your-endpoint>/v1/health/certificate?domain=www.example.com" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "name": "/CN=www.example.com",
  "subjectSN": "",
  "issuerOrganisation": "Let's Encrypt",
  "validFrom": "1704200998",
  "validTo": "1711458597",
  "signatureTypeSN": "RSA-SHA256"
}

GET /v1/health/db

Probes the database service status (multi-node returns a list).

Input: no path/query/body parameters.

Output: Returns healthStatusList (total + statuses[], with elements of healthStatus: name / ping / status (pass / fail)).

Call example:

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

Response example:

{
  "total": 1,
  "statuses": [
    {
      "name": "database",
      "ping": 128,
      "status": "pass"
    }
  ]
}

GET /v1/health/pubsub

Probes the publish-subscribe (pub-sub) service status (multi-node returns a list).

Input: no path/query/body parameters.

Output: Returns healthStatusList (total + statuses[], with elements of healthStatus: name / ping / status (pass / fail)).

Call example:

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

Response example:

{
  "total": 1,
  "statuses": [
    {
      "name": "pubsub",
      "ping": 5,
      "status": "pass"
    }
  ]
}

GET /v1/health/storage

Probes the storage device status.

Input: no path/query/body parameters.

Output: Returns healthStatus:

FieldTypeDescription
namestringService name
pingintegerHealth check duration (milliseconds)
statusstringpass / fail

Call example:

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

Response example:

{
  "name": "storage",
  "ping": 12,
  "status": "pass"
}

GET /v1/health/storage/local

Probes the local storage device status.

Input: no path/query/body parameters.

Output: Returns healthStatus:

FieldTypeDescription
namestringService name
pingintegerHealth check duration (milliseconds)
statusstringpass / fail

Call example:

curl "https://<your-endpoint>/v1/health/storage/local" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "name": "storage-local",
  "ping": 1,
  "status": "pass"
}

GET /v1/health/time

Returns a comparison between the platform's local clock and remote NTP time: used for client-side clock drift detection (time synchronization before signing requests).

Input: no path/query/body parameters.

Output: Returns healthTime:

FieldTypeDescription
remoteTimeintegerCurrent Unix timestamp (seconds) of the trusted remote server
localTimeintegerPlatform local server Unix timestamp (seconds)
diffintegerTime difference between remote and local (milliseconds)

Call example:

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

Response example:

{
  "remoteTime": 1757812200,
  "localTime": 1757812293,
  "diff": 93
}

GET /v1/health/queue/audits

Queries the audit log queue backlog: the number of audit logs waiting to be processed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/audits" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/builds

Queries the build queue backlog: the number of build tasks waiting to be processed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/builds" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/certificates

Queries the certificate queue backlog: the number of certificates waiting to be requested from Let’s Encrypt.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/certificates" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/databases

Queries the database change queue backlog: the number of database changes waiting to be processed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
namequerystringNoDefault "database_db_main"The database queue name to check, default database_db_main.
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/databases" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/deletes

Queries the background delete queue backlog: the number of destructive changes waiting to be executed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/deletes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/functions

Queries the function execution queue backlog: the number of function calls waiting to be executed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/functions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/logs

Queries the log queue backlog: the number of log entries waiting to be written.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/logs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/mails

Queries the mail queue backlog: the number of emails waiting to be sent.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/mails" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/messaging

Queries the messaging queue backlog: the number of messages waiting to be delivered.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/messaging" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/migrations

Queries the migration queue backlog: the number of migration tasks waiting to be executed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/migrations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/stats-resources

Queries the resource statistics queue backlog: the number of resource metrics waiting to be processed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/stats-resources" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/stats-usage

Queries the usage statistics queue backlog: the number of usage metrics waiting to be processed.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/stats-usage" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/webhooks

Queries the Webhook delivery queue backlog: the number of callbacks waiting to be delivered.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
thresholdqueryintegerNoDefault 5000Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue:

FieldTypeDescription
sizeintegerNumber of tasks waiting in the queue

Call example:

curl "https://<your-endpoint>/v1/health/queue/webhooks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

GET /v1/health/queue/failed/{name}

Queries the number of failed tasks in a specified queue: combined with threshold, can be used as failed backlog alerting.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
namepathstringYesEnum: v1-database, v1-deletes, v1-audits, v1-mails, v1-functions, v1-stats-resources, v1-stats-usage, v1-webhooks …Queue name, enum: v1-database, v1-deletes, v1-audits, v1-mails, v1-functions, v1-stats-resources, v1-stats-usage, v1-webhooks, v1-certificates, v1-builds, v1-screenshots, v1-messaging, v1-migrations, v1-schema-migrations.
thresholdqueryintegerNoDefault 5000Threshold; when reached (≥), a service error is returned for alerting, default 5000.

Output: Returns healthQueue (size: number of failed tasks).

Call example:

curl "https://<your-endpoint>/v1/health/queue/failed/v1-database" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "size": 8
}

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
Health.get / getAntivirus / getCache / getCertificate / getDB / getPubSub / getStorage / getStorageLocal / getQueue* / getFailedQueue/health*