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
Base URL:
https://<your-endpoint>/v1。Path prefix
/health; stateless endpoints returning thehealthStatus*model.
Authentication and Permissions
See general conventions for authentication and request header conventions.
scope:
health.read; accessible with a project API Key.
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 + path | Purpose |
|---|---|
GET /health | HTTP service status |
GET /health/anti-virus / cache / certificate / db / pubsub | Component status |
GET /health/storage / GET /health/storage/local | Storage 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/time | Platform 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:
| Field | Type | Description |
|---|---|---|
name | string | Service name |
ping | integer | Health check duration (milliseconds) |
status | string | pass / 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:
| Field | Type | Description |
|---|---|---|
version | string | Antivirus service version |
status | string | disabled / 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
domain | query | string | No | — | The domain to validate; defaults to the platform's own domain. |
Output: Returns healthCertificate:
| Field | Type | Description |
|---|---|---|
name | string | Certificate name (e.g., /CN=www.google.com) |
subjectSN | string | Subject SN |
issuerOrganisation | string | Issuing authority |
validFrom | string | Valid from (Unix seconds) |
validTo | string | Valid until (Unix seconds) |
signatureTypeSN | string | Signature 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:
| Field | Type | Description |
|---|---|---|
name | string | Service name |
ping | integer | Health check duration (milliseconds) |
status | string | pass / 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:
| Field | Type | Description |
|---|---|---|
name | string | Service name |
ping | integer | Health check duration (milliseconds) |
status | string | pass / 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:
| Field | Type | Description |
|---|---|---|
remoteTime | integer | Current Unix timestamp (seconds) of the trusted remote server |
localTime | integer | Platform local server Unix timestamp (seconds) |
diff | integer | Time 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | query | string | No | Default "database_db_main" | The database queue name to check, default database_db_main. |
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
threshold | query | integer | No | Default 5000 | Queue size threshold; when reached (≥), a service error is returned for alerting, default 5000. |
Output: Returns healthQueue:
| Field | Type | Description |
|---|---|---|
size | integer | Number 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | path | string | Yes | Enum: 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. |
threshold | query | integer | No | Default 5000 | Threshold; 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
The Health endpoints are intended for monitoring probes: when a component is abnormal, a degraded status is returned instead of 5xx (except when the gateway itself is unreachable).
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Health.get / getAntivirus / getCache / getCertificate / getDB / getPubSub / getStorage / getStorageLocal / getQueue* / getFailedQueue | /health* |