Skip to content
getgeolens.com
GeoLens Docs

Refresh Dataset

POST
/datasets/{dataset_id}/refresh
 
curl --request POST \
  --url https://example.com/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" } }'

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 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 ”
dataset_id
required
Dataset Id
string format: uuid

Request Body

Section titled “ Request Body ”
Media type application/json
Any of:
DatasetRefreshRequest

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
token
Any of:
string
<= 1000 characters
verification_policy
Verification Policy

Verification policy for this refresh. arcgis_id_set_v1 performs the stronger ArcGIS object-ID membership check.

string
default: standard
Allowed values: standard arcgis_id_set_v1
accept_blocked_run_id
Any of:
string format: uuid
auth
Any of:
ServiceAuthRequest

How one request authenticates to the remote service it names.

object
method
required
Method

How the credential is presented to the remote service. Omit the whole auth object for a public service.

string
Allowed values: bearer basic header
token
Any of:
string
<= 1000 characters
username
Any of:
string
<= 255 characters
password
Any of:
string
<= 1000 characters
header_name
Any of:
string
<= 255 characters
header_value
Any of:
string
<= 1000 characters

Responses

Section titled “ Responses ”

202

Section titled “ 202 ”

Successful Response

Media type application/json
DatasetRefreshResponse

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
run_id
required
Run Id
string format: uuid
job_id
required
Job Id
string format: uuid
dataset_id
required
Dataset Id
string format: uuid
origin_kind
required
Origin Kind

The origin this refresh re-pulled from

string
trigger
required
Trigger

Api for this endpoint; cli for the CLI door

string
status
Status
string
default: pending
message
required
Message
string
Example 
{
  "status": "pending"
}

400

Section titled “ 400 ”

Bad request — invalid payload

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Section titled “ 401 ”

Unauthorized — missing or invalid credentials

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

403

Section titled “ 403 ”

Forbidden — caller lacks write access

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Section titled “ 404 ”

Not found

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

409

Section titled “ 409 ”

Conflict — resource state prevents the operation

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Section titled “ 422 ”

Validation error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Section titled “ 429 ”

Too many requests — retry after the advertised interval

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Section titled “ Headers ”
Retry-After
integer

Seconds until the request may be retried

500

Section titled “ 500 ”

Internal server error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Section titled “ 503 ”

Service unavailable — the database could not serve the request

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}
Privacy Apache 2.0 getgeolens.com