Authentication
All endpoints (except those marked public) require a Bearer token in the Authorization header. Get a token by calling POST /v1/auth/login with email + password, or POST /v1/auth/register to create an account. The token expires — refresh it with POST /v1/auth/refresh.
Basic flow
Connect a database, ask a question, and get generated SQL + tabular results. The example below uses cURL so you can try it without installing anything.
1. Log in
Exchange email + password for an access token (and a refresh token). POST /v1/auth/login is the only auth endpoint that does not require a token.
curl -X POST https://api.easysql.net/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "supersecret"
}'Response
{
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi...",
"token_type": "bearer"
}2. Create a connector
Register your database. EasySQL will test the connection and sync the schema in the background. For WordPress sites, post only the schema and skip `config`.
curl -X POST https://api.easysql.net/v1/connectors \
-H "Authorization: Bearer $EASYSQL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "shop_wp",
"type": "mysql",
"config": {
"host": "db.example.com",
"port": 3306,
"database": "wordpress",
"user": "easysql_ro",
"password": "••••••••",
"ssl": true
}
}'3. Ask a question
POST /v1/queries is asynchronous: for full-DB connectors the queue worker runs the SQL and generates the answer; for schema-only WP connectors it returns `needs_local_execution: true` and you must POST /v1/queries/{id}/answer with the locally executed rows.
curl -X POST https://api.easysql.net/v1/queries \
-H "Authorization: Bearer $EASYSQL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"connector_id": "ds_8f3a",
"question": "How many orders this month?"
}'Response
{
"id": "qr_91ab",
"question": "How many orders this month?",
"sql_generated": "SELECT COUNT(*) FROM orders WHERE created_at BETWEEN '2026-05-01' AND '2026-05-31';",
"answer": "You received 148 orders in May.",
"chart_config": { "type": "number", "value": 148, "delta_pct": 23 },
"result_data": [{ "count": 148 }],
"needs_local_execution": false,
"status": "ready",
"created_at": "2026-05-31T18:42:11Z"
}4. Send feedback
Help EasySQL improve. Upsert thumbs-up/thumbs-down (and optional comment) against the query id.
curl -X PUT https://api.easysql.net/v1/feedbacks/{query_id} \
-H "Authorization: Bearer $EASYSQL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"positive": true,
"comment": "Spot on."
}'