Sync API docs: clarify GET /v1/sync parameters and request examples

[sharabash]

Rescoped on 2026-04-29

The original issue is partially addressed. The repo now has a dedicated Sync tutorial section that explains the offline-first flow, lastMutationAt, metadataOnly, first-sync behavior, pagination, and links back to the GET /v1/sync and POST /v1/sync API references.

This issue should now track the remaining endpoint-level documentation gaps for the generated Sync API pages.

Current State

Already covered outside the endpoint page:

• /docs/tutorials/sync/getting-started/ explains the overall Sync API flow.
• It documents lastMutationAt as a Unix timestamp in milliseconds.
• It explains metadataOnly=true and when to use it.
• It links to GET /v1/sync and POST /v1/sync API reference pages.

Already improved on the generated endpoint page:

• GET /v1/sync includes example response data.
• metadataOnly has a more useful description.
• X-Mutation-At response header is documented.

Remaining Problem

1. GET /v1/sync still lacks a concise conceptual intro on the endpoint page itself

A developer landing directly on the API reference page should immediately understand that this is a pull/delta endpoint for retrieving server-side mutations after a sync cursor.

2. mutationsSince still needs clearer parameter wording

It is currently described as "The timestamp to get mutations since." It should explicitly say:

• Unix timestamp in milliseconds
• usually the previously stored lastMutationAt
• use 0 for a full initial pull when the user already has sync history
• pair with metadataOnly=true when only checking whether newer data exists

3. Add concrete request examples

The page has response examples but still needs practical request examples, such as:

• first metadata check: GET /v1/sync?mutationsSince=0&metadataOnly=true
• pull changed resources: GET /v1/sync?mutationsSince=1731636500303&resources=BOOKMARK,COLLECTION&limit=100&page=1

4. Cross-link mutation-producing endpoints back to Sync guidance where durable

Mutation-producing endpoints document the X-Mutation-At response header, but they do not consistently point developers back to the Sync tutorial/overview. Add durable links through source OpenAPI descriptions or non-generated docs so regeneration does not erase the change.

Acceptance Criteria

• GET /v1/sync endpoint page includes a short human-readable intro before or near the generated API details.
• mutationsSince clearly says Unix milliseconds and explains common values.
• At least two request examples are visible on the docs page.
• Mutation-producing endpoints or shared docs link X-Mutation-At / sync cursor behavior to the Sync tutorial.
• Changes are made at the source OpenAPI/docs layer, not only by hand-editing generated MDX.

[benyamin-najmi]

Hi! I’d like to work on this issue if it’s still available. I plan to improve the GET /v1/sync endpoint documentation and add request examples as described.