Refresh a dataset from its source
const url = 'https://example.com/api/datasets/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/refresh';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"token":"example","verification_policy":"standard","accept_blocked_run_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","auth":{"method":"bearer","token":"example","username":"example","password":"example","header_name":"example","header_value":"example"},"expected_data_revision":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/datasets/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/refresh \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "token": "example", "verification_policy": "standard", "accept_blocked_run_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "auth": { "method": "bearer", "token": "example", "username": "example", "password": "example", "header_name": "example", "header_value": "example" }, "expected_data_revision": 1 }'Re-pull this dataset’s data from the origin it was imported from.
One request, no source pointer, no layer selection. The dataset keeps serving its current data throughout: the worker loads into an attempt-scoped staging table and swaps only once the new data is complete, so a refresh that fails leaves the live table and its freshness exactly as they were.
Different origin kinds use different execution strategies. A dataset registered from an existing PostGIS table serves directly from its origin, so refresh re-measures the live relation — recounting features, recomputing the extent, rebuilding the column schema snapshot and statistics. A dataset imported from a STAC item points to an external COG, so its refresh re-reads the item document and follows the asset if the publisher moved it. Admission, the run row and the history they write are identical across all three.
Refuses with 409 dataset_busy while another refresh or re-upload is
active for this dataset. A partial unique index prevents simultaneous
requests from both being admitted.
accept_blocked_run_id accepts a blocked run once. A blocked service
refresh is fetched again and publishes only if the result matches the run
it accepts. A blocked service re-upload is fetched again from the dataset’s
source and publishes only if its review reasons and changes match; it
answers 409 origin_changed once that source is not the one the
re-upload fetched. A blocked file replacement (an upload run) is replaced
again from the upload that run kept, and publishes only if its review
reasons and changes match. That answers 422 upload_unavailable once
the upload is gone, and 409 review_superseded once newer data has
replaced what the run was compared with. A review fingerprint is an acknowledgement, not a
secret: it keeps a replacement nobody reviewed from publishing, and any
caller with write access can still publish deliberately.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Request Body
Section titled “ Request Body ”Body of a one-request refresh. Carries no source pointer.
Everything about WHERE the data comes from is read server-side from the dataset’s stored origin binding — that is the whole feature. A client cannot re-point a dataset through this door, and a client that has been shown the wrong URL cannot refresh from it.
object
Verification policy for this refresh. arcgis_id_set_v1 performs the stronger ArcGIS object-ID membership check.
How one request authenticates to the remote service it names.
object
How the credential is presented to the remote service. Omit the whole auth object for a public service.
Responses
Section titled “ Responses ”Successful Response
Accepted dispatch of a refresh run.
Returns the run id as well as the job id: the run is the durable history
row (GET /datasets/{id}/refresh-runs) and outlives the job, which the
retention purge eventually removes.
object
The origin this refresh re-pulled from
Api for this endpoint; cli for the CLI door
Example
{ "status": "pending"}Bad request — invalid payload
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Unauthorized — missing or invalid credentials
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Forbidden — caller lacks write access
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Not found
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Conflict — resource state prevents the operation
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Validation error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Too many requests — retry after the advertised interval
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Headers
Section titled “ Headers ”Seconds until the request may be retried
Internal server error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Service unavailable — the database could not serve the request
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}