Datasets

Create Empty Dataset Endpoint

Changed on

Create an empty dataset with user-defined columns.

Creates a PostGIS table in the data schema and a catalog record.

post/datasets/create/

Request

  • The document declares no server URL.
  • Auth: one of:
    • OAuth 2 (password, token URL /api/auth/login)
    • API key in header X-Api-Key
    • API key in query parameter api_key

Request body

titlestring required

Response

Successful Response

idstring uuid required
record_idstring uuid required

Parent catalog record UUID

table_namestring required

Internal PostGIS table name

titlestring required
summarystring nullable required
sridinteger nullable

Current EPSG SRID of stored geometry

geometry_typestring nullable

OGC geometry type, e.g. MultiPolygon

has_generic_geometryboolean

True when the underlying column is generic GEOMETRY (created sketch datasets): the dataset accepts ANY geometry subtype on write regardless of the display geometry_type above. Computed on the detail endpoint only; list endpoints always report false.

is_3dboolean nullable

True if geometry has Z dimension

n_dimsinteger nullable

Number of coordinate dimensions (2, 3, or 4)

z_minnumber nullable

Minimum Z value across all features

z_maxnumber nullable

Maximum Z value across all features

feature_countinteger nullable required
extent_bboxnumber[] nullable

Bounding box [west, south, east, north] per RFC 7946 §5.2. west > east on an antimeridian-crossing extent.

licensestring nullable
attributionstring nullable

Credit line the source's terms require to be displayed wherever the data is rendered. Shown verbatim in the map viewer's attribution control.

source_organizationstring nullable
data_vintage_startstring date nullable

Start of temporal coverage

data_vintage_endstring date nullable

End of temporal coverage

source_formatstring nullable

Original file format, e.g. GPKG, SHP

source_filenamestring nullable required
tile_columnsstring[] nullable

Ordered vector-tile property allowlist; null uses zoom defaults, [] emits geometry-only tiles, list emits those properties at any zoom.

original_sridinteger nullable

EPSG SRID of the uploaded source file

current_versioninteger

Monotonic version counter

source_urlstring nullable

URL the data was originally fetched from

originstring nullable

How the data entered the catalog: upload, postgis, service, stac, or created. Computed from source_format and record_type, not stored; null for collections and VRTs, which have no origin of their own.

origin_uristring nullable

Machine-readable pointer back to the origin, written only by ingest and refresh. Distinct from source_url, which is editable descriptive metadata. Null for uploads and created datasets. It is also null for any reader who is neither the dataset's owner nor an admin — origin (above) and the freshness/health fields below are not gated and still describe the dataset's capabilities.

origin_refobject nullable

Typed per-origin payload with a kind discriminator, e.g. {"kind": "service", "service_type": "wfs", "url": "...", "layer_id": "0"}. Never contains credentials. owner-or-admin only, same redaction as origin_uri.

last_refreshed_atstring date-time nullable

Last committed successful refresh — not the last attempt

last_checked_atstring date-time nullable

Last time GeoLens contacted the origin at all, whether the attempt succeeded or failed

source_healthstring

healthy, missing, inaccessible, or unknown. 'unknown' means never probed, or an origin kind with nothing to probe.

source_health_detailstring nullable

Why the origin is not healthy, as one of a fixed set of GeoLens codes: auth_required, blocked_by_policy, item_withdrawn, network_error, not_found, server_error, timeout, unauthorized, unexpected_status. Null when healthy or never probed. Never provider text, a URL, or a response body — nothing the origin sent is stored here.

schema_drift_statusstring

none, drifted, or unknown. Set at refresh commit from the schema diff; 'unknown' until a refresh has run.

source_freshnessstring

fresh, due, overdue, or unknown, computed from last_refreshed_at against the declared update_frequency: due past one declared period, overdue past two. 'unknown' when the origin cannot be refreshed at all (created), when no cadence is declared (asNeeded, irregular, notPlanned, unknown), or when nothing has been refreshed yet. Advisory only; never blocks an operation. Distinct from the quality score's own freshness, which measures quality_detail.computed_at rather than the source.

quality_statementstring nullable
visibilitystring required

Access level: private, restricted, internal, public

created_bystring uuid nullable required
created_by_displaystring required
created_atstring date-time required
updated_atstring date-time required
last_edited_by_displaystring nullable
last_edited_atstring date-time nullable
record_statusstring

Lifecycle status. Deliberately not pinned to an enum: the values come from the workflow extension's status_order(), so an overlay may define its own. Community default order: draft, ready, internal, published.

lineage_summarystring nullable

Free-text provenance / lineage statement

update_frequencystring nullable

ISO maintenance frequency code

usage_constraintsstring nullable
access_constraintsstring nullable
sensitivity_classificationstring nullable

e.g. public, confidential, restricted

theme_categorystring[] nullable

ISO topic category codes

owner_orgstring nullable

Owning organization name

published_atstring date-time nullable
updated_bystring uuid nullable
record_typestring

Record type: 'vector_dataset' (spatial features), 'raster_dataset' (single COG), 'vrt_dataset' (VRT mosaic), 'table' (non-spatial tabular), 'map' (saved map), 'service' (catalogued remote service), 'collection' (flat dataset group), 'tiles3d_dataset' (3D Tiles tileset), 'pointcloud_dataset' (COPC point cloud).

stac_assetsobject nullable

STAC-style asset dictionary

stac_extensionsstring[] nullable
languagestring nullable

ISO 639-1 language code, e.g. en, fr

metadata_warningsstring[] nullable

Advisory warnings produced by a metadata update — e.g. a visibility or status change exposing keywords inherited from an analysis source the new audience cannot open. Only ever set on the PATCH response; the change has already applied.

Changes

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status