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" }'

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.

Two origin kinds take their own execution strategy, and neither moves any data. A dataset registered from an existing PostGIS table (#1265) has an origin that IS the table it serves from, so its 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 (#1266) is nothing but a pointer at somebody else’s 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 — v1 rejects rather than queues (Decision 5b), and the refusal comes from a partial unique index rather than a check, so two simultaneous clicks cannot both be admitted.

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 (#1220). 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
Example generated
{
  "token": "example"
}

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