Concurrency and safe retries

Manage record versions, operation identifiers and batch changes correctly.

Last updated: 10 November 2026

Record versions

Editable records carry a version field. The GeoJSON response for map features exposes the same value as properties.v. On update or deletion, the client sends the last-read value in the operation's version field. If it is no longer current, the server returns 409.

Do not guess or increment the version yourself. Use the server response as your new baseline and reread the record when needed. An operation can also change dependent equipment and connections.

Version information is required for most updates and deletions. Connections have a narrow exception for older calls, but a version is always required when location_id or slot is sent. New integrations should always send a version for connection operations too.

A single batch transaction

POST /api/p/{pid}/edit applies an ops array of 1–2,000 operations in order. Relationship, module, resource and quota checks run within the same database transaction. If any step is rejected, all changes are rolled back. Changes from a successful request are recorded under one batch.

Writes to the same project are serialised on the server. This does not replace the client's version field: your write may conflict with a value another user wrote while you were waiting.

request_id

request_id is optional for the general cookie-authenticated edit request and required for v1 editing. It must be 8–64 characters long and contain letters, digits and hyphens. Use it to make retries safe after a network interruption.

The digest is calculated from ops; the top-level note is excluded. Changing only the note and resending the same identifier does not create a new operation. Retry records older than two days may be cleared; this mechanism does not guarantee retries indefinitely.

A replay response is the result of the original write. Do not use it instead of reading current data. Results may be filtered by the module visibility at that time; reread the records if you need their current state.

Tracking changes

1. Save the cursor from GET /api/p/{pid}/features.
2. Call GET /api/p/{pid}/changes?since={cursor}.
3. Update returned features by identifier; remove those marked properties._deleted from your view.
4. Reread relevant details based on nodes, layers, talep, tahsis and circuit notifications.
5. Save the response's new cursor for the next request.

This workflow uses HTTP polling. A webhook subscription can also notify you about events; it does not replace this read workflow with complete data. Rebuild the project view when role or module scope changes rather than fetching only changed features.

Reverting a batch

POST /api/p/{pid}/changes/{batch}/revert attempts to undo an operation group. It may return 409 if records have subsequently changed or new dependencies exist. A successful revert creates a new operation group; it does not erase history.

File import, bundle restore and dedicated preview/confirm endpoints have different retry rules. Do not apply the /edit request_id behaviour to every POST endpoint. Continue with the Editing API examples.