canonical: https://jentic.com/apis/amazonaws.com/aws-cognito-sync

# AWS Amazon Cognito Sync

Jentic publishes the only available OpenAPI specification for Amazon Cognito Sync, keeping it validated and agent-ready. Amazon Cognito Sync stores and synchronizes user-scoped key-value data across a user's devices and the cloud. Each user has datasets containing string records that are merged on conflict and pushed to all signed-in devices via Amazon SNS push notifications. It is a legacy service - AWS now recommends AWS AppSync for new cross-device sync work - but it remains useful for apps already on Cognito Identity that need lightweight per-user state.

## For AI agents

Read, write, and synchronize per-user key-value datasets across a user's devices using Amazon Cognito Sync.

## Scope

Does not handle large object storage, relational queries, or arbitrary application data - use only for small per-user key-value sync tied to a Cognito identity.

## Capabilities

- Store and update user-scoped key-value records in named datasets
- Synchronize records across devices via UpdateRecords and ListRecords
- Trigger bulk publish of all dataset records to a configured Kinesis stream
- Configure push synchronization so changes propagate via SNS
- Subscribe and unsubscribe a device from dataset change notifications
- Register events and Lambda handlers that fire on dataset updates

## Use cases

### Cross-Device User Preferences

Mobile apps that already use Amazon Cognito Identity often need to keep user preferences such as theme, language, and feature toggles in sync across the user's devices. Cognito Sync stores these as records in named datasets, merges concurrent updates, and propagates changes via push notifications. Setup is a few hours once Cognito Identity is in place.

Example prompt: Call UpdateRecords on the 'preferences' dataset for an IdentityId, writing a record with key 'theme' and value 'dark', then read it back with ListRecords.

### Game Save State Sync

Casual mobile games store progress, settings, and unlocked content per player. Cognito Sync persists this state in the cloud, makes it available when the player switches devices, and resolves conflicts deterministically by sync count. Bulk publish to Kinesis enables downstream analytics on aggregated game state.

Example prompt: Write a 'save_slot_1' record containing serialized game state to a 'gameSaves' dataset and verify it appears in ListRecords for the same identity.

### Push-Driven Settings Propagation

Apps that need near-real-time propagation of dataset changes can configure push synchronization. When records update, Cognito Sync publishes via Amazon SNS to subscribed devices, which then pull the latest records. This keeps user-scoped configuration consistent without polling.

Example prompt: Call SetCognitoEvents to register a Lambda on dataset update, then SubscribeToDataset for a device's platform endpoint and confirm the event fires when UpdateRecords is called.

### Agent-Managed Per-User State

An AI agent operating on behalf of a user can persist intermediate state (such as long-running task progress or preferences) in Cognito Sync datasets without standing up a database. Through Jentic, the agent loads the UpdateRecords schema and writes records keyed by identity, then reads them back when the user returns.

Example prompt: Use UpdateRecords to write {key: 'last_task', value: 'summary_v3'} to an 'agentState' dataset and read it back with ListRecords.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /identitypools/{IdentityPoolId}/identities/{IdentityId}/datasets/{DatasetName} | Update records in a dataset |
| GET | /identitypools/{IdentityPoolId}/identities/{IdentityId}/datasets | List datasets for an identity |
| POST | /identitypools/{IdentityPoolId}/bulkpublish | Trigger bulk publish of dataset data to Kinesis |
| GET | /identitypools/{IdentityPoolId} | Describe an identity pool's sync usage |
| POST | /identitypools/{IdentityPoolId}/configuration | Configure push sync settings for a pool |

## Key resources

- **Dataset** — Create, list, describe, and delete user-scoped datasets that hold key-value records.
- **Records** — List and update records inside a dataset using ListRecords and UpdateRecords.
- **BulkPublish** — Trigger and inspect bulk publish jobs that push dataset data to Kinesis via BulkPublish and GetBulkPublishDetails.
- **PushSync** — Configure SNS-based push sync, subscribe and unsubscribe devices, and register dataset events.

## Why Jentic

- **Setup:** Wiring Amazon Cognito Sync by hand means signing every REST request with AWS Signature v4 HMAC and targeting the right regional host like cognito-sync.{region}.amazonaws.com before you can read or write a per-user dataset. Through Jentic you install once, import Amazon Cognito Sync from the API Directory, store the AWS access key and secret once, and your agent calls it.
- **Permission scoping:** Cognito Sync puts the identity pool, identity, and dataset in the URL path (/identitypools/{IdentityPoolId}/identities/{IdentityId}/datasets/{DatasetName}), so a rule can pin your agent to one identity pool and nothing else. You also choose the operations it may call, so a read like ListDatasets can be allowed while DeleteDataset stays out unless you add it.
- **Credential handling:** Your AWS access key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time when the request is signed. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'sync a user's key-value records across devices' or 'list datasets for an identity', and Jentic returns the matching Cognito Sync operation with its input schema, so the agent calls the correct endpoint without browsing the AWS service reference.

## Related APIs

- **Amazon Cognito Identity** — Provides the IdentityId that every Cognito Sync dataset is scoped to.
- **AWS AppSync** — GraphQL API service with built-in offline sync and conflict resolution.
- **Firebase APIs** — Google's Firebase platform APIs including realtime sync.

## FAQ

### Why is there no official OpenAPI spec for Amazon Cognito Sync?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon Cognito Sync 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 Amazon Cognito Sync API use?

AWS Signature v4 (HMAC) over the Cognito Identity credentials issued to the user's device. Jentic stores the underlying AWS credentials in its vault, signs requests for the agent, and never exposes the secret access key.

### Can I store arbitrary blobs with the Amazon Cognito Sync API?

No. Cognito Sync records are limited to small string key-value pairs (up to 1 MB per dataset). For larger objects, store them in Amazon S3 and keep only the S3 key in the Cognito Sync record.

### What are the rate limits for the Amazon Cognito Sync API?

Per-identity-pool rate limits apply to all sync operations and are enforced per AWS Region. Expect TooManyRequestsException under heavy concurrent UpdateRecords and back off exponentially; for analytics-style throughput, use BulkPublish to Kinesis instead.

### How do I synchronize records across devices with Amazon Cognito Sync through Jentic?

Search Jentic for 'sync user records across devices', load the UpdateRecords schema, and execute it against /identitypools/{IdentityPoolId}/identities/{IdentityId}/datasets/{DatasetName} with the record patches. Other devices then call ListRecords to pull the latest state.

### Should I use Amazon Cognito Sync for new applications?

AWS recommends AWS AppSync for new cross-device sync workloads because it supports richer data models and offline conflict resolution. Cognito Sync is still supported and is a reasonable fit for existing Cognito Identity apps that need lightweight key-value sync.

### Can I limit what my agent is allowed to do with the Amazon Cognito Sync API?

Yes. Because you run Jentic One yourself, your own rules decide which Cognito Sync operations and credentials the agent may use. Cognito Sync puts the identity pool, identity, and dataset in the URL path, so a rule can pin your agent to a single identity pool and no other. You also pick the operations it may call, so a read like ListDatasets or ListRecords can be allowed while DeleteDataset stays out unless you explicitly add it.