Sync apis

docs/content_apis_versioned/4.0.0/posts-controller-find-one.api.mdx

@@ -40,4 +40,3 @@ Most recent visible comment summary when available. Use the dedicated comment en
 Quran Reflect lesson or reflection not found or has been deleted
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/content_apis_versioned/4.0.0/posts-controller-get-all-comment.api.mdx

@@ -36,4 +36,3 @@ All comments for the Quran Reflect lesson or reflection returned with total coun
 Quran Reflect lesson or reflection not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/content_apis_versioned/4.0.0/posts-controller-get-comments.api.mdx

@@ -36,4 +36,3 @@ Comments for the Quran Reflect lesson or reflection retrieved with pagination me
 Quran Reflect lesson or reflection not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/content_apis_versioned/posts-controller-find-one.api.mdx

@@ -40,4 +40,3 @@ Most recent visible comment summary when available. Use the dedicated comment en
 Quran Reflect lesson or reflection not found or has been deleted
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/content_apis_versioned/posts-controller-get-all-comment.api.mdx

@@ -36,4 +36,3 @@ All comments for the Quran Reflect lesson or reflection returned with total coun
 Quran Reflect lesson or reflection not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/content_apis_versioned/posts-controller-get-comments.api.mdx

@@ -36,4 +36,3 @@ Comments for the Quran Reflect lesson or reflection retrieved with pagination me
 Quran Reflect lesson or reflection not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/tutorials/oidc/example-integration.mdx

@@ -235,6 +235,7 @@ fly deploy
 
 ## Next Steps
 
-- **[Full OAuth2 Guide](/docs/tutorials/oidc/getting-started-with-oauth2)** — Detailed walkthrough with AI prompts
-- **[Mobile Apps](/docs/tutorials/oidc/mobile-apps)** — iOS, Android, React Native guides
-- **[User APIs Reference](/docs/category/user-related-apis)** — All available endpoints
+- **[Full OAuth2 Guide](/docs/tutorials/oidc/getting-started-with-oauth2)** - Detailed walkthrough with AI prompts
+- **[SDK](/docs/sdk)** - Client SDK for mobile and web apps
+- **[Mobile Apps](/docs/tutorials/oidc/mobile-apps)** - iOS, Android, React Native guides
+- **[User APIs Reference](/docs/category/user-related-apis)** - All available endpoints

docs/tutorials/sync/getting-started.mdx

@@ -124,8 +124,9 @@ When the user creates data offline, push mutations to the server using `POST /v1
 
 ### API References
 
-- [GET /v1/sync (Get mutations)](/docs/user_related_apis_prelive/auth-get-v-1-sync)
-- [POST /v1/sync (Sync local mutations)](/docs/user_related_apis_prelive/auth-post-v-1-sync)
+- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations)
+- [POST /v1/sync (Sync local mutations)](/docs/user_related_apis_versioned/sync-local-mutations)
+- [POST /v1/bookmarks (Add bookmark)](/docs/user_related_apis_versioned/auth-post-v-1-bookmarks) — for bookmark field requirements
 
 ## Using metadataOnly for Efficiency
 
@@ -139,7 +140,7 @@ This is significantly faster than a full sync (single DB query vs multiple joins
 
 For the full request/response schema, see:
 
-- [GET /v1/sync (Get mutations)](/docs/user_related_apis_prelive/auth-get-v-1-sync)
+- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations)
 
 ## Filtering & Pagination
 
@@ -154,6 +155,7 @@ When `metadataOnly=true`, the response includes only `lastMutationAt` (no pagina
 ## Important Notes
 
 - **Mutation limits** — `POST /v1/sync` accepts a maximum of 100 mutations per request.
+- **Direct endpoints** — Direct mutation endpoints (e.g. `POST /v1/bookmarks`) require `lastMutationAt` as a query param and return the `X-Mutation-At` header for updating `lastMutationAt`.
 
 ## Next Steps
 

docs/tutorials/sync/handling-conflicts.mdx

@@ -117,7 +117,19 @@ This quickly retrieves the current `lastMutationAt` without fetching all mutatio
 
 See the full request/response schema in the API reference:
 
-- [GET /v1/sync (Get mutations)](/docs/user_related_apis_prelive/auth-get-v-1-sync)
+- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations)
+
+## Direct Mutation Endpoints
+
+When using direct mutation endpoints (e.g., `POST /v1/bookmarks`), the same conflict rules apply:
+
+1. Include `lastMutationAt` as a query parameter
+2. Check for 409 responses
+3. Update `lastMutationAt` from the `X-Mutation-At` response header
+
+:::tip Always Capture the Header
+Store the `X-Mutation-At` header value after every successful mutation. If you miss it, use `metadataOnly=true` to recover.
+:::
 
 ## Best Practices
 

docs/tutorials/sync/offline-first-patterns.mdx

@@ -118,7 +118,7 @@ Apply local changes immediately, then enqueue mutations for sync. When the serve
 
 ### Handling Sync Results
 
-When the server returns mutation results, update local records with server IDs and timestamps, then dequeue the synced mutations and persist the returned `lastMutationAt`.
+When the server returns mutation results, update local records with server IDs and timestamps, then dequeue the synced mutations and persist the new cursor. Use the returned `lastMutationAt` for `/v1/sync` responses, and read `X-Mutation-At` from direct mutation endpoints such as `POST /v1/bookmarks`.
 
 ## Error Handling & Retry
 

docs/user-related-apis/1.0.0/reading-sessions-vs-activity-days.mdx

@@ -33,4 +33,3 @@ Tracks daily activity/progress (by date + type). This powers streaks, goals, and
 - [Add/update activity day](/docs/user_related_apis_versioned/1.0.0/auth-post-v-1-activity-days)
 - [Get activity days](/docs/user_related_apis_versioned/1.0.0/auth-get-v-1-activity-days)
 - [Estimate reading time](/docs/user_related_apis_versioned/1.0.0/auth-get-v-1-activity-days-estimate-reading-time)
-

docs/user-related-apis/reading-sessions-vs-activity-days.mdx

@@ -33,4 +33,3 @@ Tracks daily activity/progress (by date + type). This powers streaks, goals, and
 - [Add/update activity day](/docs/user_related_apis_versioned/auth-post-v-1-activity-days)
 - [Get activity days](/docs/user_related_apis_versioned/auth-get-v-1-activity-days)
 - [Estimate reading time](/docs/user_related_apis_versioned/auth-get-v-1-activity-days-estimate-reading-time)
-

docs/user_related_apis_prelive/add-collection-bookmark.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/add-collection.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/add-note.api.mdx

@@ -87,4 +87,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/add-user-bookmark.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/comments-controller-create.api.mdx

@@ -51,4 +51,3 @@ User not authenticated
 Post or parent comment not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/comments-controller-delete-comment.api.mdx

@@ -43,4 +43,3 @@ User not authorized to delete this comment
 Comment not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/comments-controller-get.api.mdx

@@ -35,4 +35,3 @@ Comment replies with pagination
 Parent comment not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/comments-controller-toggle-like.api.mdx

@@ -39,4 +39,3 @@ User not authenticated
 Comment not found
 
 </div><div></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/delete-bookmark.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/delete-collection-bookmark-by-details.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/delete-collection.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-

docs/user_related_apis_prelive/delete-note-by-id.api.mdx

@@ -75,4 +75,3 @@ The server is currently unable to handle the request due to a temporary overload
 The server did not receive a timely response from the upstream server.
 
 </div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"message"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"gateway_timeout"}}></SchemaItem><SchemaItem collapsible={false} name={"success"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","example":false}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"message\": \"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server\",\n  \"type\": \"gateway_timeout\",\n  \"success\": false\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>
-