The Amazon DynamoDB Transactions API is the most interesting single API in the DynamoDB record, and it is only two operations. TransactGetItems groups up to 100 Get actions into one atomic read. TransactWriteItems groups up to 100 write actions across up to 100 distinct items in one or more tables, in the same account and Region, and either all of them land or none do. Everything else DynamoDB does is one item or best-effort batch. This is the call where the database makes a promise.
DynamoDB itself scores 78.8, exemplar, with Agent Readiness at 36.4, agent-ready.
What the API ships
The API page carries an OpenAPI contract, an overlay, a JSON Schema, JSON-LD and a link to AWS’s API reference. The contract is honest about the wire shape: DynamoDB is not REST. Every call is a POST to https://dynamodb.{region}.amazonaws.com with an X-Amz-Target header of the form DynamoDB_20120810.OperationName. To fit that into OpenAPI, the paths are written as fragments, /#TransactGetItems and /#TransactWriteItems. It works as a document. It is a workaround, and anyone generating a client from it should know that.
The request schema caps TransactItems at maxItems: 100 and carries ClientRequestToken, described as the identifier that makes the write idempotent. That is the feature an agent needs most: a retried transactional write that does not apply twice. The overlay’s phrasing gets it right, asking “Can I retry a transactional write safely without applying it twice?”
Where the contract falls short
The record also holds AWS’s own Smithy model, dynamodb-2012-08-10.json. It defines 58 operations for DynamoDB. The five OpenAPI splits on apis.io (Batch, Items, Queries, Tables, Transactions) hold 15 between them. The provider record says api_count: 1; the site builds six API pages.
For this API specifically, Smithy lists nine errors on TransactWriteItems, including TransactionCanceledException, TransactionInProgressException and IdempotentParameterMismatchException. The OpenAPI documents two responses besides 200: a 400 “Invalid request parameters” and a 409 “Transaction conflict”. The cancellation reasons, which are how a caller learns which condition check failed, are not described. And the security scheme declares SigV4 as type: http, scheme: bearer. SigV4 is a signature, not a bearer token. Those are our defects, not AWS’s: the first-party model is right there and the contract did not use it.
| Source | Operations | Errors on TransactWriteItems |
|---|---|---|
| AWS Smithy model | 58 (all of DynamoDB) | 9 |
| apis.io OpenAPI splits | 15 (all five) | 2 non-200 responses |
Takeaway
The Transactions API is small, precise and agent-relevant: atomicity plus an idempotency token is exactly what a tool-calling agent needs before it writes. What would move the record is regenerating the OpenAPI from the Smithy model, which would bring the 43 missing operations, the full error list and a correct SigV4 scheme in one pass, and reconciling api_count with the pages we build.
See the API at apis.io/apis/amazon-dynamodb/amazon-dynamodb-transactions-api/.