canonical: https://jentic.com/apis/amazonaws.com/qldb-session # AWS Amazon QLDB Session Jentic publishes the only available OpenAPI specification for Amazon QLDB Session, keeping it validated and agent-ready. QLDB Session is the low-level transactional protocol behind Amazon Quantum Ledger Database. It exposes a single SendCommand operation that multiplexes session start, transaction begin, PartiQL statement execution, fetch-page, commit, and end-session commands over one signed request channel. Most applications use the QLDB driver or shell on top of this API; direct use is appropriate when building a custom QLDB client, language binding, or agent transport layer. ## For AI agents Drive QLDB transactions end-to-end (start session, execute PartiQL, fetch results, commit) over a single multiplexed SendCommand operation. ## Scope Does not create or delete ledgers, manage permissions, or export data - use for transaction-level PartiQL execution against an existing QLDB ledger only. ## Capabilities - Start a QLDB session bound to a specific ledger via the StartSession command variant - Begin a transaction inside an active session with the StartTransaction variant - Execute PartiQL statements against the active transaction using the ExecuteStatement variant - Fetch additional result pages for a statement with the FetchPage variant when results are paged - Commit a transaction with a hash digest match using the CommitTransaction variant - End or abort a session and transaction cleanly via the EndSession and AbortTransaction variants ## Use cases ### Custom QLDB Driver Build a QLDB client in a language without an official driver by implementing the SendCommand protocol directly. Each transaction follows the StartSession > StartTransaction > ExecuteStatement (one or more) > CommitTransaction > EndSession sequence with the same session token threaded through every call. Useful for niche runtimes that need ledger access without porting the AWS SDK driver. Example prompt: Issue SendCommand with StartSession {LedgerName:'my-ledger'}, capture SessionToken, then issue SendCommand with StartTransaction and the SessionToken ### Atomic Multi-Statement Ledger Updates Run several PartiQL statements inside one ACID transaction by reusing the same session and transactionId across ExecuteStatement calls, then commit with a hash digest. Common in audit-grade systems that must record a multi-record fact (e.g., asset transfer) atomically and verifiably. Example prompt: After StartTransaction, issue SendCommand with ExecuteStatement {Statement:'INSERT INTO Vehicle ?', Parameters:[ionDoc]} for each row, then issue CommitTransaction with the running hash digest ### Paged PartiQL Reads Stream large result sets out of QLDB by issuing FetchPage commands while a transaction is open. ExecuteStatement returns the first page and a NextPageToken; subsequent FetchPage calls reuse the SessionToken and TransactionId until the iterator is exhausted, then the transaction commits or aborts. Useful for export jobs and reconciliation reports. Example prompt: Issue ExecuteStatement {Statement:'SELECT * FROM Audit'} then loop FetchPage with the returned NextPageToken until no more pages are returned ### AI Agent Ledger Tool via Jentic An agent that needs verifiable, append-only writes uses Jentic to discover SendCommand, load its schema, and walk the StartSession > StartTransaction > ExecuteStatement > CommitTransaction sequence. Jentic stores AWS credentials in its vault and signs every call with SigV4, leaving the agent to focus on the PartiQL payload. Example prompt: Use Jentic to search 'execute partiql in a qldb transaction', load SendCommand, and execute the StartSession then ExecuteStatement variants for the target ledger ## Key resources - **Session** — Lifecycle commands for opening, ending, and threading session tokens - **Transaction** — Begin, commit, and abort transactions inside an active session - **Statement** — Execute PartiQL statements and fetch additional result pages ## Why Jentic - **Setup:** Wiring QLDB Session by hand means computing SigV4 HMAC signatures, routing to the regional session.qldb host, and threading session tokens, transaction hash digests, and Amazon Ion encoding through a single SendCommand call yourself. Through Jentic you install once, import Amazon QLDB Session from the API Directory, store your AWS access keys once, and your agent calls it with signing handled per request. - **Permission scoping:** This API exposes a single SendCommand operation whose command variant travels in the request body, so you limit the agent to that operation and control behaviour by which variants it sends, such as StartSession, StartTransaction, and ExecuteStatement for reads. Commit-related variants like CommitTransaction are included only when you grant them, and the agent still supplies the correct hash digest for any write. - **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and used to produce a SigV4 signature per SendCommand request. The raw secret access key never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'execute PartiQL inside a QLDB transaction', and Jentic returns SendCommand with its variant schema so the agent populates exactly one of the session or transaction commands per call without reading the reference docs. ## Related APIs - **AWS RDS Data API** — Run SQL on relational databases without sessions; QLDB Session is the equivalent transport for ledger PartiQL - **Amazon Redshift Data API** — Stateless SQL execution against a Redshift cluster; QLDB Session keeps stateful ledger sessions - **AWS Resource Access Manager** — Share QLDB ledger access across accounts via resource shares ## FAQ ### Why is there no official OpenAPI spec for Amazon QLDB Session? AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon QLDB Session via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the QLDB Session API use? QLDB Session uses AWS SigV4 HMAC request signing with an AWS access key ID and secret. Through Jentic, AWS credentials are stored in the vault and SigV4 signatures are computed per request so the agent never sees raw secrets. ### Why does this API have only one operation? QLDB Session multiplexes every command (StartSession, StartTransaction, ExecuteStatement, FetchPage, CommitTransaction, AbortTransaction, EndSession) through a single SendCommand call where exactly one variant is populated per request. The variant chosen determines the action. ### Should I use this API directly or use the QLDB driver? Most applications should use the official QLDB driver (or qldb-shell) which wraps SendCommand with retry, hash-tracking, and Ion serialization. Use SendCommand directly only when implementing a custom driver or runtime where the driver is not available. ### Can I run cross-ledger transactions? No. Each session is bound to one LedgerName at StartSession; transactions and statements only see that ledger. To work across ledgers, open a separate session per ledger. ### How do I execute a PartiQL statement through Jentic? Search Jentic for 'execute partiql in a qldb transaction', load SendCommand, and execute it with the StartSession variant first to get a SessionToken, then issue SendCommand again with StartTransaction and ExecuteStatement variants. Install with pip install jentic. ### Can I limit what my agent is allowed to do with the Amazon QLDB Session API? Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API exposes a single SendCommand operation whose behaviour is set by the command variant sent in the request body. You can allow read-oriented variants such as StartSession, StartTransaction, and ExecuteStatement while withholding write variants like CommitTransaction unless you explicitly grant them, and any commit still requires the correct hash digest. Your AWS access keys stay under your instance's control, so the agent signs each call without ever seeing the raw secret.