Skip to main content
POST
/
v1
/
schemas
curl --request POST \
  --url https://api.dynamosql.com/v1/schemas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "schemaName": "myschema",
  "region": "us-east-1",
  "accountId": "123456789012",
  "roleArn": "arn:aws:iam::123456789012:role/DynamoSQLReadRole",
  "externalId": "dsql-ext-7f3a9c2b",
  "tableAllowlist": [
    "Users",
    "Orders",
    "Products"
  ]
}
'
{
  "success": true,
  "data": {
    "tenantId": "tenant-abc123",
    "schemaName": "myschema",
    "region": "us-east-1",
    "accountId": "123456789012",
    "roleArn": "arn:aws:iam::123456789012:role/DynamoSQLReadRole",
    "externalId": "dsql-ext-7f3a9c2b",
    "tableAllowlist": [
      "Users",
      "Orders",
      "Products"
    ],
    "status": "active",
    "createdAt": "2026-03-11T10:00:00.000Z",
    "updatedAt": "2026-03-11T10:00:00.000Z"
  }
}
Required scope: schemas:write
Before creating a schema, follow the IAM Setup guide to configure the trust policy and permissions DynamoSQL needs to assume your role. After creating a schema, use Validate Role to confirm the configuration is correct.

Authorizations

​
Authorization
string
header
required

Bearer token obtained from POST /v1/auth/token. Pass in the Authorization header as Bearer <token>.

Body

application/json
​
schemaName
string
required

Logical name for this schema. Used in SQL as the schema qualifier: SELECT * FROM {schemaName}.{tableName}. Must be unique within the tenant. Case-insensitive at query time; stored as-provided.

Example:

"myschema"

​
region
string
required

AWS region where the DynamoDB tables reside. Must be a valid AWS region identifier (e.g., us-east-1, eu-west-2).

Example:

"us-east-1"

​
accountId
string
required

12-digit AWS account ID that owns the DynamoDB tables.

Example:

"123456789012"

​
roleArn
string
required

Full ARN of the IAM role to assume. The role must have a trust policy permitting DynamoSQL to assume it with the provided externalId. See the IAM Setup guide for the required trust policy and permission set.

Example:

"arn:aws:iam::123456789012:role/DynamoSQLReadRole"

​
externalId
string
required

External ID to include in sts:AssumeRole. Must match the sts:ExternalId condition in the role's trust policy. Generate a random string (UUID recommended) and store it in both DynamoSQL and your IAM role.

Example:

"dsql-ext-7f3a9c2b"

​
tableAllowlist
string[]

Optional list of DynamoDB table names this schema may access. Omit to allow all tables visible to the role. Pass ["*"] to explicitly allow all tables with wildcard validation. Individual names are matched exactly (case-sensitive).

Example:
["Users", "Orders"]

Response

Schema created. A background metadata refresh has been started.

​
success
boolean
required

true when the request was processed without errors, false otherwise. Always present.

​
data
object

A DynamoSQL schema record. A schema connects a logical name to the IAM role and AWS region DynamoSQL uses to access DynamoDB on your behalf via cross-account role assumption.

​
error
object

Present in the response body when success is false.