hosting
POST /v1/sites/{siteId}/database/query
Run one guarded SQL statement against the site's WordPress database.
Authentication
Send an API key as a bearer token. The key must carry the sites.view permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/sites/{siteId}/database/query \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "sql": <string> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
One statement, checked before anything reaches the site: a verb allow-list (reads SELECT, SHOW, DESCRIBE, EXPLAIN, WITH; writes INSERT, UPDATE, DELETE, REPLACE only with allow_write), no comments, no INTO OUTFILE/LOAD_FILE, no deliberate delays, and a WHERE clause on every UPDATE/DELETE. Schema changes and privileges are never run. Anything else answers 422 naming the rule. ⛔ Reads run inside START TRANSACTION READ ONLY, so the database itself refuses a write the check missed. A write runs in a transaction that is rolled back when it touches more rows than the limit, and always when dry_run is set — that is the preview: it answers how many rows the write would change. ⛔ 200 with ok: false when MySQL refuses the statement (its own diagnosis). The audit row records the verb and row counts — never the statement or its result. Requires sites.view and sites.panel_access. Fleet WordPress sites only.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
siteId (path) | Uuid | Yes | Site ID (UUIDv7). |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
sql | string | Yes | One SQL statement. A trailing ; is allowed. |
allow_write | boolean | No | Permit INSERT/UPDATE/DELETE/REPLACE. |
dry_run | boolean | No | Run a write and roll it back, answering the rows it would change. |
max_rows | integer | No | Rows returned for a read. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
ok | boolean | Yes | — |
verb | string | Yes | — |
write | boolean | Yes | — |
dry_run | boolean | No | True when a write was rolled back as a preview. |
error | string | No | MySQL's own refusal, when ok is false. |
affected | integer | No | Rows a write changed (or would change). |
total_rows | integer | No | — |
columns | string[] | No | — |
rows | object[] | No | — |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429 · 503