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: '{"columns":[{"name":"example","type":"text"}],"title":"example"}'
};

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 '{ "columns": [ { "name": "example", "type": "text" } ], "title": "example" }'

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

columns

required

Columns

Array<object>

ColumnDefinition

object

name

required

Name

string

type

required

Type

string

Allowed values: text integer float date boolean

title

required

Title

string

<= 500 characters

Responses

201

Successful Response

application/json

DatasetResponse

object

access_constraints

Any of:

string
null

string

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

column_info

Any of:

Array<object>
null

Array<object>

ColumnInfo

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

object

domain_type

Any of:

string
null

string

name

required

Name

string

sample_values

Any of:

Array
null

Array

semantic_role

Any of:

string
null

string

stats

Any of:

object
null

object

key

additional properties

any

type

required

Type

string

created_at

required

Created At

string format: date-time

created_by

required

Any of:

string
null

string format: uuid

created_by_display

required

Created By Display

string

current_version

Current Version

Monotonic version counter

integer

default: 1

data_vintage_end

Any of:

string
null

string format: date

data_vintage_start

Any of:

string
null

string format: date

extent_bbox

Any of:

Array<number>
null

Array<number>

feature_count

required

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

required

string format: uuid

is_3d

Any of:

boolean
null

boolean

language

Any of:

string
null

string

last_edited_at

Any of:

string
null

string format: date-time

last_edited_by_display

Any of:

string
null

string

license

Any of:

string
null

string

lineage_summary

Any of:

string
null

string

n_dims

Any of:

integer
null

integer

original_srid

Any of:

integer
null

integer

owner_org

Any of:

string
null

string

published_at

Any of:

string
null

string format: date-time

quality_detail

Any of:

QualityDetail
null

QualityDetail

Automated quality assessment results.

object

attribute_completeness

required

Attribute Completeness

number

<= 100

computed_at

Any of:

string
null

string format: date-time

crs_defined

Any of:

number
null

number

<= 100

geometry_validity

Any of:

number
null

number

<= 100

metadata_completeness

required

Metadata Completeness

number

<= 100

overall

required

Overall

number

<= 100

quality_statement

Any of:

string
null

string

raster

Any of:

RasterMetadata
null

RasterMetadata

object

band_count

Any of:

integer
null

integer

bands

Bands

Array<object>

default:

RasterBandInfo

object

color_interp

Any of:

string
null

string

dtype

required

Dtype

Pixel data type, e.g. uint8, float32

string

index

required

Index

1-based band index

integer

nodata

Any of:

string
null

string

compression

Any of:

string
null

string

connect

Any of:

RasterConnect
null

RasterConnect

object

download_url

Any of:

string
null

string

s3_uri

Any of:

string
null

string

tile_url

required

Tile Url

Titiler tile endpoint for this raster

string

crs_is_geographic

Any of:

boolean
null

boolean

epsg

Any of:

integer
null

integer

height

Any of:

integer
null

integer

is_dem

Any of:

boolean
null

boolean

nodata

Any of:

string
null

string

res_x

Any of:

number
null

number

res_y

Any of:

number
null

number

resolution_strategy

Any of:

string
null

string

size_bytes

Any of:

integer
null

integer

source_count

Any of:

integer
null

integer

status

Any of:

string
null

string

tile_url

Any of:

string
null

string

vrt_type

Any of:

string
null

string

width

Any of:

integer
null

integer

record_id

required

Record Id

Parent catalog record UUID

string format: uuid

record_status

Record Status

Lifecycle status: draft, ready, published

string

default: draft

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

sensitivity_classification

Any of:

string
null

string

source_filename

required

Any of:

string
null

string

source_format

Any of:

string
null

string

source_organization

Any of:

string
null

string

source_url

Any of:

string
null

string

<= 2000 characters

srid

Any of:

integer
null

integer

stac_assets

Any of:

object
null

object

key

additional properties

StacAsset

object

description

Any of:

string
null

string

href

required

Href

string

roles

Any of:

Array<string>
null

Array<string>

size_bytes

Any of:

integer
null

integer

title

Any of:

string
null

string

type

Any of:

string
null

string

stac_extensions

Any of:

Array<string>
null

Array<string>

summary

required

Any of:

string
null

string

table_name

required

Table Name

Internal PostGIS table name

string

theme_category

Any of:

Array<string>
null

Array<string>

tile_columns

Any of:

Array<string>
null

Array<string>

title

required

Title

string

update_frequency

Any of:

string
null

string

updated_at

required

Updated At

string format: date-time

updated_by

Any of:

string
null

string format: uuid

usage_constraints

Any of:

string
null

string

visibility

required

Visibility

Access level: private, restricted, internal, public

string

z_max

Any of:

number
null

number

z_min

Any of:

number
null

number

Example

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

400

Bad request — invalid payload

application/problem+json

ProblemDetail

object

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Unauthorized — missing or invalid credentials

application/problem+json

ProblemDetail

object

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

403

Forbidden — caller lacks write access

application/problem+json

ProblemDetail

object

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Not found

application/problem+json

ProblemDetail

object

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

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

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Validation error

application/problem+json

ProblemDetail

object

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

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

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

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

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

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

detail

required

Any of:

string

status

required

Status

integer

title

required

Title

string

type

Type

string

default: about:blank

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

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