Run via API

The API lets a program, or a command line, run the same queries as the SQL box. Not a developer? Use Run a SQL instead: it does the same with buttons.

Before you start

Create your login: open Run a SQL, enter your e-mail address and follow the link we send you.
After you sign in, your API token is shown once. Copy it now.
Open a terminal and give the token a name, then run the commands below.

Sample commands

First put your token in a variable: export DBSHERIFF_TOKEN= followed by the token you were shown. These run in bash or zsh; on Windows use the SQL box or a bash shell such as WSL. The SQL box's Copy as curl button writes the same call with the same variable. The commands print only the body, so tell the answers apart by the code word in error.code, not by a number (add -i to a command to see the status line too). On your first query you may get unavailable: see the list at the end of this section.

1. Who am I: your state, your expiry and, under engines, your pseudonym as login (null until your first statement).

curl -sS https://api-demo.dbsheriff.ai/v1/me \
  -H "Authorization: Bearer $DBSHERIFF_TOKEN"

2. The tables, no token needed. Each has a group: sensitive_real and fixture_synthetic are the sensitive ones, decoy the bait, normal_real the regular ones. The quotes keep zsh happy. Names come without their schema, so write financial_data.credit_cards in SQL.

curl -sS "https://api-demo.dbsheriff.ai/v1/tables?engine=postgresql"

3. A regular table. The body holds engine, statement and an optional max_rows; the answer holds your login, the columns and the rows.

curl -sS -X POST https://api-demo.dbsheriff.ai/v1/query \
  -H "Authorization: Bearer $DBSHERIFF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"engine": "postgresql",
 "statement": "SELECT gics_sector, COUNT(*) AS companies FROM securities GROUP BY gics_sector ORDER BY companies DESC",
 "max_rows": 20}
JSON

4. A sensitive table: you get the rows, or statement_ended (HTTP 409).

curl -sS -X POST https://api-demo.dbsheriff.ai/v1/query \
  -H "Authorization: Bearer $DBSHERIFF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"engine": "postgresql",
 "statement": "SELECT symbol, period_end, revenue, net_income FROM income_statement WHERE symbol = 'AAPL' ORDER BY period_end DESC LIMIT 5"}
JSON

To run another statement from section 4, put it in the statement field on one line. The answers:

503 unavailable: on your first query, your login is still being made; it can also mean the demo is paused. Wait a little and send it again.
409 statement_ended: the database closed your session, which on this demo usually means DBSheriff stopped the statement. 409 busy: one of your statements is still running.
202 with a job_id: past 20 seconds. GET /v1/queries/<job_id> reads it, POST /v1/queries/<job_id>/cancel stops it. After a cancel, reading the job shows 422 statement_error; that is the cancel, not a fault.
401 invalid_token token missing, replaced or expired. 400 (invalid_request, unsupported_statement or statement_too_long) refused by the demo's rules. 422 statement_error refused by the database. 429 rate_limited or cooling_down too fast, or paused (Retry-After). 403 account_locked your login is locked. 504 timeout ran too long.

Then watch it in the Monitor UI

Open the demo page and click Monitor UI. Each statement you send appears there under your login name (it starts with dv). Statements that look risky can be ended, and a fast burst of them can get your login locked: that is what the demo is for.