hosting

POST /v1/sites/{siteId}/database/query

Run one guarded SQL statement against the site's WordPress database.

All hosting endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

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

NameTypeRequiredWhat it is
siteId (path)UuidYesSite ID (UUIDv7).

Request body

NameTypeRequiredWhat it is
sqlstringYesOne SQL statement. A trailing ; is allowed.
allow_writebooleanNoPermit INSERT/UPDATE/DELETE/REPLACE.
dry_runbooleanNoRun a write and roll it back, answering the rows it would change.
max_rowsintegerNoRows returned for a read.

Response

NameTypeRequiredWhat it is
okbooleanYes—
verbstringYes—
writebooleanYes—
dry_runbooleanNoTrue when a write was rolled back as a preview.
errorstringNoMySQL's own refusal, when ok is false.
affectedintegerNoRows a write changed (or would change).
total_rowsintegerNo—
columnsstring[]No—
rowsobject[]No—

Errors this endpoint can return

401 · 403 · 404 · 422 · 429 · 503