From d243a8288a19549faffb981dbb547f058d64f42e Mon Sep 17 00:00:00 2001 From: MikaKerman Date: Thu, 20 Aug 2026 21:36:16 +0300 Subject: [PATCH] docs(api): clarify synced_at semantics and the 1970-01-01 sentinel Smoke-testing the beta showed some columns return synced_at 1970-01-01T00:00:00. That's expected: synced_at marks created/last-changed (not last-seen), pre-existing rows may carry an epoch placeholder, and it's safe for incremental (captured in the full scan, re-emitted on next change). Document it so consumers treat synced_at as a change marker, not an absolute freshness signal. Co-authored-by: Cursor --- docs/api/incremental-sync.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/api/incremental-sync.mdx b/docs/api/incremental-sync.mdx index 88152ba7a..0cb59b6cd 100644 --- a/docs/api/incremental-sync.mdx +++ b/docs/api/incremental-sync.mdx @@ -37,6 +37,17 @@ curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ Timestamps are UTC ISO-8601. + + **What `synced_at` means.** `synced_at` marks when an object was **created or + last changed** in Elementary — not when it was last *seen*. Unchanged objects + keep their existing `synced_at`, and some objects that predate this field may + show a `1970-01-01T00:00:00` placeholder. This is expected and safe for + incremental loading: every object is returned by the initial full scan + (regardless of `synced_at`), and any later change gives it a fresh `synced_at`, + so it reappears in the `synced_since` feed. Treat `synced_at` as a change + marker for driving upserts, not as an absolute "last refreshed" timestamp. + + ## Recommended loop 1. Store the wall-clock time `T` when you start a sync.