Keeping a copy current
A sync keeps your own copy of a company's defects current without reading everything each time. This page covers paging, the sync recipe, what a sync cannot see, and an example script that does it all.
Paging
Every list answers with data, next_cursor and as_of. Follow next_cursor by passing it back as cursor, and stop when it is null. A cursor works only with the same list and the same filters that produced it.
limit is how many rows a page holds. It defaults to 50 and the most allowed is 200. A larger value is refused, not reduced.
Every page of one walk carries the same as_of: the moment the walk was bounded at. A walk always ends, even while people keep editing defects.
Lists have no totals. Without updated_since, GET /v1/defects is ordered oldest first, by when each defect was opened.
Recipe
- 01Walk
GET /v1/defectsto the end with noupdated_since, and keep theas_ofof its first page. - 02On each later run, ask for
updated_sinceset to that lastas_ofminus 5 minutes, and walk it to the end. - 03Save each defect by its
id, replacing the copy you hold. - 04When the walk has finished, keep the
as_ofof its first page for next time.
updated_since is inclusive, and the results are ordered by when each defect was last edited. The 5 minute overlap is deliberate: a defect can arrive twice, and saving by id makes that harmless. A duplicate is safe, a miss is not.
The value must end in Z or an offset such as +10:00, and a + must be percent-encoded. It may carry up to six fractional digits, so pass back the as_of you were given, less the overlap.
curl -G https://api.issuesid.com/v1/defects \
--data-urlencode "updated_since=2026-11-12T21:25:05.728431Z" \
-d limit=200 \
-H "Authorization: Bearer $ISSUESID_API_KEY"GET /v1/form-submissions and GET /v1/diary-entries take updated_since too, and the same recipe works for them.
Edit sources
modified_source says where a defect's last edit came from: app, api or sync. An edit made through the API reads api. Edits that arrive from Aconex or from the earlier IssuesId platform read sync.
Reconciliation
A walk of defects is not the whole picture, so do these each run:
- →List
GET /v1/projectsin full. A project that has dropped out of the list means its defects are gone from your view. - →Read each project's job checklist again with
GET /v1/projects/{projectId}/job-checklist-tasks, because tasks have noupdated_since. Only a key for all projects can read checklists. - →Read
GET /v1/formsin full. A form published again shows a highercurrent_version. - →Read locations and trades in full too. They are small lists and take no
updated_since.
Filed answers
The filed forms list is a summary: who filed each form, when, on which project, and where it stands. It carries no answers. Read each updated submission by id with GET /v1/form-submissions/{submissionId} for its answers.
Only a key for all projects can read filed forms. A key for a list of projects gets 403 forbidden, not an empty list.
valueisnullwhen there is no answer, and arrays are never empty. A multi-select, photo or picker answer with nothing chosen isnull, never[].
Deletions
A deleted defect comes back in the walk as a deletion marker with five fields: id, project_id, deleted, deleted_at and modified_at. Branch on deleted: a live defect carries deleted as false, and a marker carries true. Remove your copy by id.
A plain list and GET /v1/defects/{defectId} never return a deleted defect.
Deletion markers are kept for 90 days. A walk that starts further back than that is refused with 422 sync_window_expired, because a deletion in the gap could be missed. When you see it, run a full walk again from the start and replace your copy.
Limits
A walk cannot see everything, and these are the limits.
- →A row that leaves your view leaves no deletion marker. That covers a project that was deleted and a project removed from a project-list key, so reconcile projects each run.
- →Diary trade and person names are read live, so renaming one does not move an entry's
modified_at. - →The diary has its own clock and sends no webhooks, so read
GET /v1/diary-entrieswithupdated_sinceevery so often. - →An edit from the earlier IssuesId platform that only touches its own save time shows in a later read but sends no webhook.
- →A write that failed on a project linked to the earlier platform shows only when that platform sends the row again.
Job checklist tasks and form definitions have no updated_since at all, as the reconciliation list says.
Example script
The example script keeps a local copy current with the recipe above. It is one file for Node 20 or later, with no dependencies. It does four things:
- →It reads every project and defect on the first run, then only what was edited since.
- →It keeps the last
as_ofin a state file and starts each run 5 minutes before it. - →It removes a defect when its deletion marker arrives, and drops the defects of a project that has gone.
- →It waits and retries on 429 and 503, and starts again with a full read after
sync_window_expired.
Variables
The script reads four environment variables. ISSUESID_API_KEY is required and needs only a key that can read. ISSUESID_API_BASE_URL, ISSUESID_STATE_FILE and ISSUESID_DATA_FILE are optional, and default to the live API and two JSON files in the folder you run it from. The state file moves forward only after a walk has finished and been saved, so a failed run never skips an edit.
curl -O https://www.issuesid.com/developers/sync-example.mjs
node sync-example.mjsDownload the script and set ISSUESID_API_KEY first. The script stores projects and defects in a local JSON file so it runs anywhere. In your own system, replace its four store functions with writes into your own database and leave the rest alone.
Every endpoint, parameter and response is in the API reference.