Skip to main content

​
Overview

DynamoSQL lets you query your DynamoDB tables with SQL. This guide walks through obtaining an access token and running your first query against the API.

​
Prerequisites

  • A DynamoSQL account — sign up at dynamosql.com
  • Your client_id and client_secret from the portal

​
Step 1 — Obtain an access token

DynamoSQL uses OAuth 2.0 client credentials. Exchange your client credentials for a bearer token: 
curl -X POST https://auth.dynamosql.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=query:execute"
The token is valid for one hour. Cache and reuse it; request a new one when it expires.

​
Step 2 — Run a query

Call POST /v1/query with your bearer token: 
curl -X POST https://api.dynamosql.com/v1/query \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM myschema.orders LIMIT 10",
    "mode": "execute"
  }'

​
Step 3 — Interpret the response

A successful response looks like this: 
{
  "success": true,
  "data": {
    "columns": ["order_id", "customer_id", "total"],
    "data": [
      [1001, "cust-42", 99.99],
      [1002, "cust-07", 14.50]
    ],
    "firstRowIdx": 0,
    "resumeIdx": 10,
    "planTime": 3,
    "execTime": 42
  }
}
  • success — always check this first. If false, read error and detailedError.
  • data.columns — column names in the same order as each row array.
  • data.data — array of rows (each row is an array of values).
  • data.resumeIdx — present when there are more rows; pass it back to fetch the next page.
  • data.planTime / data.execTime — parse+plan time and total elapsed time in milliseconds.
resumeIdx is absent (not null) when the result set is exhausted. Always use "resumeIdx" in data (not data.resumeIdx !== null) to test for more pages.

​
Next steps