> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamosql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Refresh Metadata
> Refresh the cached DynamoDB table metadata for a schema.
Required scope: `schemas:write`
## OpenAPI
````yaml POST /v1/schemas/{schemaName}/refresh-metadata
openapi: 3.0.3
info:
title: DynamoSQL API
version: 0.1.0
license:
name: Proprietary
url: https://dynamosql.com
description: >
Complete API for DynamoSQL — authentication, SQL query planning and
execution, schema management, and usage metering.
All endpoints are reachable at `api.dynamosql.com`.
**Authentication** uses `POST /v1/auth/token` with your API client
credentials. See the [Authentication
guide](https://docs.dynamosql.com/guides/authentication)
for the full token exchange flow.
**API client scopes** control which endpoints a programmatic client can
access.
Valid scopes: `query`, `schemas:read`, `schemas:write`, `usage:read`.
Endpoints note their required scope in their description.
**Error responses** always follow the same envelope:
```json
{ "success": false, "error": { "message": "..." } }
```
servers:
- url: https://api.dynamosql.com
description: Production
security:
- cognitoJwt: []
tags:
- name: Authentication
description: >
Obtain a JWT bearer token using your API client credentials. This token is
required for all other endpoints. See the Authentication guide for details
on the token exchange flow and scope management.
- name: Query
description: SQL planning and execution.
- name: Schemas
description: >
Connect DynamoSQL to DynamoDB tables in your AWS account. A schema pairs a
name with the IAM role and AWS region DynamoSQL uses to assume
cross-account access.
- name: Usage
description: Metered usage — requests, rows returned, and DynamoDB read units.
paths:
/v1/schemas/{schemaName}/refresh-metadata:
post:
tags:
- Schemas
summary: Refresh schema metadata
description: >
Manually triggers a metadata refresh for all DynamoDB tables visible to
the schema's IAM role. DynamoSQL uses this cached metadata to resolve
column names, pick indexes for queries, and populate the portal's table
browser.
Call this after adding new tables to DynamoDB, modifying a table's key
schema, or adding/removing a Global Secondary Index. The portal also
provides a **Refresh** button that calls this endpoint.
Note: This operation is optional because DynamoSQL automatically
invalidates metadata after 15 minutes, and refreshes on the next
request. However, you may want to call it manually to immediately pick
up changes in your DynamoDB tables without waiting for the next
automatic refresh cycle.
If the schema's status is `disabled`, the refresh is skipped and
`skipped: true` is returned — no error. Re-enable the schema first.
API clients require the `schemas:write` scope.
Partial failures (some tables succeed, others fail) return `200 OK` with
`ok: false` and a summary message — they do not return a 4xx or 5xx
status. Check `ok` and `message` in the response data.
operationId: refreshSchemaMetadata
parameters:
- in: path
name: schemaName
required: true
schema:
type: string
description: The schema name to refresh.
example: myschema
responses:
'200':
description: >
Refresh attempted. Check `data.ok` for success or partial failure. A
`200` response does not guarantee all tables were refreshed
successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
ok:
type: boolean
description: >
`true` if all tables were refreshed successfully.
`false` if any table failed or the refresh was
skipped.
message:
type: string
description: >
Human-readable summary of the refresh outcome,
including failure details when applicable.
refreshedAt:
type: string
format: date-time
description: >
ISO 8601 timestamp of when the refresh completed,
when applicable.
tableCount:
type: integer
description: Number of tables successfully refreshed.
failedTableCount:
type: integer
description: Number of tables that failed to refresh.
deletedCount:
type: integer
description: >
Number of orphaned cache entries deleted (tables
that no longer exist in DynamoDB).
skipped:
type: boolean
description: >
`true` when the schema is `disabled` and the
refresh was not attempted.
examples:
success:
summary: All tables refreshed
value:
success: true
data:
ok: true
message: >-
Refresh complete. 5 table(s) refreshed, 0 failed, 1
deleted.
refreshedAt: '2026-03-11T10:00:00.000Z'
tableCount: 5
failedTableCount: 0
deletedCount: 1
skipped: false
partial-failure:
summary: Partial failure — some tables failed
value:
success: true
data:
ok: false
message: >-
Refresh complete. 4 table(s) refreshed, 1 failed:
Invoices (describe: Access Denied).
refreshedAt: '2026-03-11T10:00:00.000Z'
tableCount: 4
failedTableCount: 1
deletedCount: 0
skipped: false
skipped:
summary: Schema is disabled
value:
success: true
data:
ok: false
message: Schema is disabled. Enable it before refreshing.
skipped: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
ApiResponse:
type: object
required:
- success
properties:
success:
type: boolean
description: >
`true` when the request was processed without errors, `false`
otherwise. Always present.
data: {}
error:
$ref: '#/components/schemas/ApiError'
ApiError:
type: object
description: Present in the response body when `success` is `false`.
properties:
message:
type: string
description: Human-readable description of what went wrong.
code:
type: string
description: Machine-readable error code, when available.
requestId:
type: string
description: |
Request correlation ID. Include this when contacting support.
responses:
BadRequest:
description: >
Validation error — a required field is missing, a value is out of range,
a date is malformed, or the request body is otherwise invalid. Check the
`error.message` field for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: startDate must be before or equal to endDate
Unauthorized:
description: >
Missing `Authorization` header, expired JWT, or token issuer/audience
does not match the DynamoSQL Cognito user pool.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: Unauthorized
Forbidden:
description: >
The caller lacks the required role or a tenant-scoping violation was
detected.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: Tenant admin access required
securitySchemes:
cognitoJwt:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Bearer token obtained from `POST /v1/auth/token`. Pass in the
`Authorization` header as `Bearer `.
````