Quickstart

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 clientId and clientSecret from the portal

Step 1 — Obtain an access token

Exchange your API client credentials for a bearer token:

curl -X POST https://api.dynamosql.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

import requests

resp = requests.post(
    "https://api.dynamosql.com/v1/auth/token",
    json={
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
    },
)
token = resp.json()["data"]["accessToken"]

const resp = await fetch("https://api.dynamosql.com/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  }),
});
const { accessToken } = (await resp.json()).data;

const resp = await fetch("https://api.dynamosql.com/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  }),
});
const { accessToken }: { accessToken: string } = (await resp.json()).data;

The token is valid for one hour. Cache and reuse it; refresh it with POST /v1/auth/refresh 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"
  }'

import requests

resp = requests.post(
    "https://api.dynamosql.com/v1/query",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "sql": "SELECT * FROM myschema.orders LIMIT 10",
        "mode": "execute",
    },
)
result = resp.json()

const resp = await fetch("https://api.dynamosql.com/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sql: "SELECT * FROM myschema.orders LIMIT 10",
    mode: "execute",
  }),
});
const result = await resp.json();

const resp = await fetch("https://api.dynamosql.com/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sql: "SELECT * FROM myschema.orders LIMIT 10",
    mode: "execute",
  }),
});
const result = await resp.json();

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

Authentication — principal types, scopes, and token refresh
Pagination — looping through large result sets
SQL Reference — what SQL is supported

Get Started

Guides

MCP Server

API Reference

SQL Reference

Changelog

Overview

Prerequisites

Step 1 — Obtain an access token

Step 2 — Run a query

Step 3 — Interpret the response

Next steps

​Overview

​Prerequisites

​Step 1 — Obtain an access token

​Step 2 — Run a query

​Step 3 — Interpret the response

​Next steps

Overview

Prerequisites

Step 1 — Obtain an access token

Step 2 — Run a query

Step 3 — Interpret the response

Next steps