Create Empty Dataset Endpoint

POST

/datasets/create/

const url = 'https://example.com/datasets/create/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"example","columns":[{"name":"example","type":"text"}]}'
};

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/datasets/create/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "columns": [ { "name": "example", "type": "text" } ] }'

Create an empty dataset with user-defined columns.

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

Authorizations

Request Body^required

application/json

CreateEmptyDatasetRequest

object

title

required

Title

string

<= 500 characters

columns

required

Columns

Array<object>

ColumnDefinition

object

name

required

Name

string

type

required

Type

string

Allowed values: text integer float date boolean

Responses

201

Successful Response

application/json

DatasetResponse

object

required

string format: uuid

record_id

required

Record Id

Parent catalog record UUID

string format: uuid

table_name

required

Table Name

Internal PostGIS table name

string

title

required

Title

string

summary

required

Any of:

string
null

string

srid

Any of:

integer
null

integer

geometry_type

Any of:

string
null

string

has_generic_geometry

Has Generic Geometry

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 (fix #430 codex r18); list endpoints always report false.

boolean

is_3d

Any of:

boolean
null

boolean

n_dims

Any of:

integer
null

integer

z_min

Any of:

number
null

number

z_max

Any of:

number
null

number

feature_count

required

Any of:

integer
null

integer

extent_bbox

Any of:

Array<number>
null

Array<number>

column_info

Any of:

Array<object>
null

Array<object>

ColumnInfo

Describes a single column in a dataset’s attribute table.

object

name

required

Name

string

type

required

Type

string

semantic_role

Any of:

string
null

string

domain_type

Any of:

string
null

string

sample_values

Any of:

Array
null

Array

stats

Any of:

object
null

object

key

additional properties

any

license

Any of:

string
null

string

attribution

Any of:

string
null

string

source_organization

Any of:

string
null

string

data_vintage_start

Any of:

string
null

string format: date

data_vintage_end

Any of:

string
null

string format: date

quality_detail

Any of:

QualityDetail
null

QualityDetail

Automated quality assessment results.

object

overall

required

Overall

number

<= 100

metadata_completeness

required

Metadata Completeness

number

<= 100

geometry_validity

Any of:

number
null

number

<= 100

attribute_completeness

required

Attribute Completeness

number

<= 100

crs_defined

Any of:

number
null

number

<= 100

computed_at

Any of:

string
null

string format: date-time

source_format

Any of:

string
null

string

source_filename

required

Any of:

string
null

string

tile_columns

Any of:

Array<string>
null

Array<string>

original_srid

Any of:

integer
null

integer

current_version

Current Version

Monotonic version counter

integer

default: 1

source_url

Any of:

string
null

string

<= 2000 characters

origin

Any of:

string
null

string

origin_uri

Any of:

string
null

string

<= 2000 characters

origin_ref

Any of:

object
null

object

key

additional properties

any

last_refreshed_at

Any of:

string
null

string format: date-time

last_checked_at

Any of:

string
null

string format: date-time

source_health

Source Health

Healthy, missing, inaccessible, or unknown. ‘unknown’ means never probed, or an origin kind with nothing to probe.

string

default: unknown

source_health_detail

Any of:

string
null

string

schema_drift_status

Schema Drift Status

None, drifted, or unknown. Set at refresh commit from the schema diff; ‘unknown’ until a refresh has run.

string

default: unknown

source_freshness

Source Freshness

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.

string

default: unknown

quality_statement

Any of:

string
null

string

visibility

required

Visibility

Access level: private, restricted, internal, public

string

created_by

required

Any of:

string
null

string format: uuid

created_by_display

required

Created By Display

string

created_at

required

Created At

string format: date-time

updated_at

required

Updated At

string format: date-time

last_edited_by_display

Any of:

string
null

string

last_edited_at

Any of:

string
null

string format: date-time

collections

Any of:

Array<object>
null

Array<object>

CollectionRef

Minimal reference to a collection a dataset belongs to.

object

required

string format: uuid

name

required

Name

string

record_status

Record Status

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.

string

default: draft

lineage_summary

Any of:

string
null

string

derived_from

Any of:

DerivedFromResponse
null

DerivedFromResponse

Provenance for an analysis output: what it came from, and how.

fix(#765 review): declared as a model rather than dict[str, Any]. The dict spelled itself into the checked-in OpenAPI as bare additionalProperties: true, so both generated SDKs lost the shape — the TypeScript one degraded to an index signature and the Python one to an empty additional-properties container. The stable shape was documented in prose and mirrored by hand in the frontend types while the SDKs, which is where most consumers actually meet it, could not use it type-safely.

params stays untyped on purpose: it is the operation’s own parameter dict, so its keys differ per operation (distance_meters for a buffer, mask_source/mask_dataset_id for a clip), and it is additionally REDACTED per requester — visible_derived_from drops any embedded dataset id the caller cannot see. A union of per-operation models would describe a shape the redaction is free to punch holes in.

object

dataset_id

required

Dataset Id

The dataset this one was derived from

string format: uuid

operation

required

Operation

Analysis operation that produced it

string

params

required

Params

Operation parameters, minus any dataset reference the requester cannot access

object

key

additional properties

any

created_at

required

Created At

string format: date-time

update_frequency

Any of:

string
null

string

usage_constraints

Any of:

string
null

string

access_constraints

Any of:

string
null

string

sensitivity_classification

Any of:

string
null

string

theme_category

Any of:

Array<string>
null

Array<string>

owner_org

Any of:

string
null

string

published_at

Any of:

string
null

string format: date-time

updated_by

Any of:

string
null

string format: uuid

record_type

Record Type

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).

string

default: vector_dataset

raster

Any of:

RasterMetadata
null

RasterMetadata

object

epsg

Any of:

integer
null

integer

crs_is_geographic

Any of:

boolean
null

boolean

res_x

Any of:

number
null

number

res_y

Any of:

number
null

number

band_count

Any of:

integer
null

integer

is_dem

Any of:

boolean
null

boolean

nodata

Any of:

string
null

string

compression

Any of:

string
null

string

width

Any of:

integer
null

integer

height

Any of:

integer
null

integer

size_bytes

Any of:

integer
null

integer

tile_url

Any of:

string
null

string

bands

Bands

Array<object>

default:

RasterBandInfo

object

index

required

Index

1-based band index

integer

dtype

required

Dtype

Pixel data type, e.g. uint8, float32

string

nodata

Any of:

string
null

string

color_interp

Any of:

string
null

string

connect

Any of:

RasterConnect
null

RasterConnect

object

download_url

Any of:

string
null

string

tile_url

required

Tile Url

Titiler tile endpoint for this raster

string

s3_uri

Any of:

string
null

string

status

Any of:

string
null

string

vrt_type

Any of:

string
null

string

source_count

Any of:

integer
null

integer

resolution_strategy

Any of:

string
null

string

stac_assets

Any of:

object
null

object

key

additional properties

StacAsset

object

href

required

Href

string

type

Any of:

string
null

string

title

Any of:

string
null

string

description

Any of:

string
null

string

roles

Any of:

Array<string>
null

Array<string>

size_bytes

Any of:

integer
null

integer

stac_extensions

Any of:

Array<string>
null

Array<string>

language

Any of:

string
null

string

metadata_warnings

Any of:

Array<string>
null

Array<string>

Example

{
  "has_generic_geometry": false,
  "current_version": 1,
  "source_health": "unknown",
  "schema_drift_status": "unknown",
  "source_freshness": "unknown",
  "record_status": "draft",
  "record_type": "vector_dataset",
  "raster": {
    "bands": []
  }
}

400

Bad request — invalid payload

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

Unauthorized — missing or invalid credentials

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

Forbidden — caller lacks write access

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

Not found

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

Conflict — resource state prevents the operation

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

Validation error

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

Too many requests — retry after the advertised interval

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

Retry-After

integer

Seconds until the request may be retried

500

Internal server error

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

Service unavailable — the database could not serve the request

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

Create Empty Dataset Endpoint

Authorizations

Request Body required

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

Headers

500

Example

503

Example

Request Body^required