GeoVault Developer API

This reference documents the 92 registered API/data operations in GeoVault (81 unique paths), including the authenticated dataset detail page. Paths are shown exactly as registered, without a /geovault prefix. The service listens on http://127.0.0.1:8085. A reverse proxy commonly mounts it at /geovault; BASE_PATH and X-Forwarded-Prefix can therefore change the public URL.

Authentication and authorization

All routes pass through RequireLogin and RequireGeoVaultServiceAccess. The acugis_session cookie is the usable API credential. Shared authentication attempts Authorization: Bearer <PAT>, but GeoVault's auth store has no TokenStore; bearer PATs are currently treated as unauthenticated. GeoVault implements no JWT, OAuth, or API-key authentication and emits no CORS headers.

Service ACL resource service/geovault requires view for GET/HEAD, edit for mutations, and admin for /connections*, /api/connections*, and /api/database-services*. These path checks use unprefixed request paths; under BASE_PATH, some intended admin classifications may degrade to the normal view/edit classification. This is known behavior, not a compatibility guarantee.

Handlers that perform dataset checks use resource type geovault_dataset and permission view, edit, or admin as stated below. 401 means no usable login, 403 means an ACL denial, 500 means an internal/storage failure, and 503 commonly means the metadata database or a dependent service is unavailable.

User-Agent: GeoVault/1.0 is set by GeoVault for outbound URL imports only. API clients are not required to send it.

Shared request profiles

• Upload multipart: file is required. Effective accepted extensions are .gpkg, .geojson, .json, .zip, .tif, and .tiff; a .zip must contain .shp, .dbf, and .shx. The initial extension gate also lists .kml, .qgs, and .qgz, but ingest type detection rejects them, so clients must not rely on those formats. folder_id is optional. Optional PostGIS sidecar fields are postgis_import, postgis_destination, postgis_connection_id, postgis_database_id, postgis_new_database_name, postgis_schema, postgis_table_name, postgis_mode, postgis_owner_mode, postgis_owner_username, postgis_owner_password, postgis_pg_service_name, postgis_host, postgis_port, postgis_dbname, postgis_user, postgis_password, and postgis_sslmode. Optional GeoServer sidecar fields are publish_to_geoserver, geoserver_connection_id, geoserver_workspace, geoserver_store_name, geoserver_layer_name, geoserver_style, and geoserver_publish_immediate.
• URL import JSON: dataset_name, url, version_label, project_id, folder_id, plus the PostGIS and GeoServer sidecar fields above.
• S3 import JSON: dataset_name, bucket, key, endpoint, region, access_key, secret_key, path_style, mode (import or remote), version_label, project_id, folder_id, plus the same sidecars.
• Row filters: filters is a JSON-encoded array of {column, op, value} objects. Row-list queries also accept limit (default 50, maximum 500), offset, sort, and order (asc or desc).
• Unless a response is identified as a file, XML, HTML, or GeoJSON, it is JSON.

Folders

GET /api/folders

Item	Details
Purpose	List folders visible to the current user.
Auth	Service view; current login; folder access filtering.
Parameters	Query archived=only returns archived folders only.
Body	None.
Response	200 array of folder summaries: id, name, optional description, owner, owner_id, group_name, updated_at, archived, archived_at; dataset_count, permissions.
Status/Errors	401, 403, 500.
Notes	Active folders are returned by default.

POST /api/folders

Item	Details
Purpose	Create a folder.
Auth	Service edit; current login.
Parameters	None.
Body	JSON name, description, group_name.
Response	201 folder summary.
Status/Errors	400 invalid JSON/values; 401, 403, 503, 500.
Notes	Requires the metadata database.

GET /api/folders/{id}

Item	Details
Purpose	Get one accessible folder.
Auth	Service view; folder access.
Parameters	Path id (positive integer).
Body	None.
Response	200 folder summary.
Status/Errors	400 invalid ID; 401, 403, 404, 500.
Notes	Dataset count is computed at request time.

PUT /api/folders/{id}

Item	Details
Purpose	Rename or redescribe a folder.
Auth	Service edit; folder access.
Parameters	Path id.
Body	JSON name, description.
Response	200 updated folder summary.
Status/Errors	400, 401, 403, 404, 503, 500.
Notes	Does not change group_name.

POST /api/folders/{id}/archive

Item	Details
Purpose	Archive a folder.
Auth	Service edit; folder access.
Parameters	Path id.
Body	None.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 404, 503, 500.
Notes	Requires the metadata database.

QGIS projects

GET /api/qgis-projects

Item	Details
Purpose	List published QGIS runtime projects and snapshot counts.
Auth	Service view.
Parameters	None.
Body	None.
Response	200 array with id, name, optional timestamps/render mode/viewer URL, snapshot_count, runtime_status, can_edit.
Status/Errors	401, 403, 502, 503.
Notes	Proxies the QGIS publish service.

GET /api/qgis-projects/{id}

Item	Details
Purpose	Get a published QGIS project summary.
Auth	Service view.
Parameters	Path id.
Body	None.
Response	200 QGIS project summary.
Status/Errors	400, 401, 403, 404, 502, 503.
Notes	Snapshot count requires a second upstream request.

GET /api/qgis-projects/{id}/versions

Item	Details
Purpose	List runtime and snapshot versions.
Auth	Service view.
Parameters	Path id.
Body	None.
Response	200 {project_id, versions:[{version,created_at,size_bytes,is_runtime}]}; runtime is version 0.
Status/Errors	401, 403, upstream status, 502, 503.
Notes	Proxies the QGIS publish service.

POST /api/qgis-projects/{id}/versions/{version}/restore

Item	Details
Purpose	Restore a QGIS project snapshot as runtime.
Auth	Service edit.
Parameters	Path id, version.
Body	None.
Response	Upstream JSON and status.
Status/Errors	401, 403, upstream status, 502, 503.
Notes	Proxies the QGIS publish service.

GET /api/qgis-projects/{id}/download

Item	Details
Purpose	Download the current QGIS project package.
Auth	Service view.
Parameters	Path id.
Body	None.
Response	200 upstream binary download.
Status/Errors	401, 403, upstream status, 502, 503.
Notes	Content headers are passed through.

GET /api/qgis-projects/{id}/versions/{version}/download

Item	Details
Purpose	Download a QGIS project snapshot ZIP.
Auth	Service view.
Parameters	Path id, version.
Body	None.
Response	200 upstream binary download.
Status/Errors	401, 403, upstream status, 502, 503.
Notes	Content headers are passed through.

Import and upload

POST /import-url

Item	Details
Purpose	Ingest a dataset from an HTTP(S) URL.
Auth	Service edit; current login; resulting dataset registration.
Parameters	Optional query folder_id; body folder_id takes precedence when positive.
Body	URL import JSON profile above.
Response	201 ingest result, optionally including PostGIS/GeoServer sidecar results.
Status/Errors	400, 401, 403, 409, 422, 500, 503.
Notes	url and dataset_name are required.

POST /import-s3

Item	Details
Purpose	Import or remotely register an S3 object.
Auth	Service edit; current login; resulting dataset registration.
Parameters	Optional query folder_id; body folder_id takes precedence when positive.
Body	S3 import JSON profile above.
Response	201 ingest result, optionally including sidecar results.
Status/Errors	400, 401, 403, 409, 422, 500, 503.
Notes	bucket and key are required; mode=remote may have no local file.

POST /projects/{id}/upload

Item	Details
Purpose	Upload a new dataset/version under a project.
Auth	Service edit; current login; dataset edit when extending an existing dataset.
Parameters	Path id (project ID); optional query folder_id (multipart folder_id is also accepted).
Body	Upload multipart profile above.
Response	201 JSON ingest result when Accept: application/json; otherwise 303 redirect to the dataset page.
Status/Errors	400, 401, 403, 409, 413, 422, 500, 503.
Notes	Send Accept: application/json for API behavior.

GET /projects/{id}/versions

Item	Details
Purpose	List visible versions in a project.
Auth	Service view; dataset visibility filtering.
Parameters	Path id.
Body	None.
Response	200 array of Version objects.
Status/Errors	400, 401, 403, 500.
Notes	Version schema is defined in the OpenAPI document.

GET /api/discovery

Item	Details
Purpose	Return GeoVault items for federation discovery.
Auth	Service view; dataset visibility filtering.
Parameters	None.
Body	None.
Response	200 {service,resource_type,items:[{id,title,description,url,thumbnail,category}]}.
Status/Errors	401, 403, 500.
Notes	URLs honor request path-prefix handling.

Dataset catalog and lifecycle

GET /datasets

Item	Details
Purpose	List visible dataset names grouped from the version catalog.
Auth	Service view; dataset view.
Parameters	None. folder_id and all other query parameters are ignored.
Body	None.
Response	200 JSON dataset listing.
Status/Errors	401, 403, 500.
Notes	ACL-filtered across the complete version catalog; unlike /datasets-summary, this handler does not implement folder, type, or archive filtering.

GET /datasets-summary

Item	Details
Purpose	List detailed dataset summaries.
Auth	Service view; dataset visibility filtering.
Parameters	Query type (exact case-insensitive match to recorded dataset type, normally raster or vector); folder_id (positive integer; invalid/non-positive values are ignored); archived=only|true|1 for archived only, archived=include|all for both, otherwise active only.
Body	None.
Response	200 array with name/title/type/latest version/file and datasource fields, owner, timestamps, visibility, permissions, archive and folder fields.
Status/Errors	401, 403, 500.
Notes	Empty optional fields are omitted.

GET /datasets/{name}

Item	Details
Purpose	Render the authenticated dataset detail page.
Auth	Service view; dataset view.
Parameters	Path name.
Body	None.
Response	200 text/html.
Status/Errors	401, 403, 404, 500.
Notes	This is an HTML data route, not a JSON endpoint.

POST /datasets/{name}/upload

Item	Details
Purpose	Upload a new version of a named dataset.
Auth	Service edit; dataset edit.
Parameters	Path name; optional query folder_id (multipart folder_id is also accepted).
Body	Upload multipart profile above.
Response	201 JSON ingest result. This named-dataset route always takes the JSON branch.
Status/Errors	400, 401, 403, 409, 413, 422, 500, 503.
Notes	Send Accept: application/json for JSON.

GET /datasets/{name}/versions

Item	Details
Purpose	List versions for a dataset.
Auth	Service view; dataset view.
Parameters	Path name; optional folder_id.
Body	None.
Response	200 {versions:[Version]} newest first.
Status/Errors	401, 403, 500.
Notes	Returned dataset spelling follows the request.

DELETE /datasets/{name}/versions/{version}

Item	Details
Purpose	Delete a non-latest dataset version and its data.
Auth	Service edit; dataset edit.
Parameters	Path name, integer version.
Body	None.
Response	200 success JSON.
Status/Errors	400, 401, 403, 404; 409 latest version; 500.
Notes	Latest registered version cannot be deleted.

POST /datasets/{name}/rename

Item	Details
Purpose	Rename a dataset across registry, catalog, and metadata files.
Auth	Service edit; dataset edit.
Parameters	Path name.
Body	JSON {name}.
Response	200 {success,name}.
Status/Errors	400, 401, 403, 409, 500.
Notes	New name must pass import dataset-name validation.

POST /datasets/{name}/archive

Item	Details
Purpose	Archive a dataset.
Auth	Service edit; dataset edit.
Parameters	Path name.
Body	None.
Response	200 {"success":true}.
Status/Errors	401, 403, 404, 500, 503.
Notes	Requires the metadata database.

POST /datasets/{name}/restore

Item	Details
Purpose	Restore an archived dataset.
Auth	Service edit; dataset edit.
Parameters	Path name.
Body	None.
Response	200 {"success":true}.
Status/Errors	401, 403, 404, 500, 503.
Notes	Requires the metadata database.

POST /datasets/{name}/clone

Item	Details
Purpose	Clone a dataset and selected associated state.
Auth	Service edit; source dataset view; clone operation authorization.
Parameters	Path name.
Body	JSON {name?, clone_metadata?, clone_versions?, clone_publish_config?}; omitted/blank name defaults to <source> (Copy).
Response	200 clone result.
Status/Errors	400, 401, 403, 404, 409, 500.
Notes	clone_publish_config is accepted but currently ignored.

DELETE /datasets/{name}

Item	Details
Purpose	Permanently delete a dataset after confirmation.
Auth	Service edit; dataset admin.
Parameters	Path name; required query confirm=true.
Body	None.
Response	200 success JSON.
Status/Errors	400 missing confirmation; 401, 403, 404; 409 dataset is not archived when metadata DB is configured; 500.
Notes	Destructive. Archive first when the metadata database is available.

Metadata, preview, download, publication, and lineage

GET /datasets/{name}/metadata

Item	Details
Purpose	Read user-maintained dataset metadata and archive/folder state.
Auth	Service view; dataset view.
Parameters	Path name.
Body	None.
Response	200 metadata fields title, description, tags, citation, attribution, keywords, notes, optional IDs/timestamps, plus archive/folder fields.
Status/Errors	401, 403, 500.
Notes	Defaults are returned when the metadata database is absent.

POST /datasets/{name}/metadata

Item	Details
Purpose	Save user-maintained metadata.
Auth	Service edit; dataset edit.
Parameters	Path name.
Body	JSON title, description, tags, citation, attribution, keywords, notes.
Response	200 saved metadata.
Status/Errors	400, 401, 403, 500, 503.
Notes	Blank title defaults to dataset name.

POST /versions/{id}/publish

Item	Details
Purpose	Publish a version through the unified publish target.
Auth	Service edit; dataset edit resolved from version.
Parameters	Path id is required by routing but ignored by the handler.
Body	JSON required version_id (positive version-row ID), optional dataset consistency check.
Response	Upstream publish result.
Status/Errors	400, 401, 403, 404, 409, 502, 503.
Notes	The body version_id, not the path id, selects the version. Raster versions publish to QGIS; vector versions register with the tile server.

GET /api/versions/{id}/publish-capability

Item	Details
Purpose	Report whether and where a version can be published.
Auth	Service view; dataset view resolved from version.
Parameters	Path id.
Body	None.
Response	200 {available,target?,reason?}.
Status/Errors	400, 401, 403, 404, 500.
Notes	Does not publish.

GET /versions/{id}/lineage

Item	Details
Purpose	Return parent/operation lineage for a version.
Auth	Service view; dataset view.
Parameters	Path id.
Body	None.
Response	200 lineage JSON containing the version and related lineage data.
Status/Errors	400, 401, 403, 404, 500.
Notes	Uses Version operation and parent fields.

POST /versions/{id}/rollback

Item	Details
Purpose	Create a new version rolled back from the selected version.
Auth	Service edit; dataset edit.
Parameters	Path id.
Body	Optional JSON {reason}; blank/omitted reason defaults to Rollback to v<source>.
Response	200 new Version/rollback result.
Status/Errors	400, 401, 403, 404, 409, 500.
Notes	Does not rewrite historical versions.

GET /versions/{id}/download

Item	Details
Purpose	Download the local file for a version.
Auth	Service view; dataset view.
Parameters	Path id.
Body	None.
Response	200 application/octet-stream attachment.
Status/Errors	401, 403, 404.
Notes	Remote-only versions and versions without a local path return 404.

GET /metadata

Item	Details
Purpose	Extract or return technical metadata for a dataset version.
Auth	Service view; dataset view.
Parameters	Required query dataset, version.
Body	None.
Response	200 dataset technical metadata JSON.
Status/Errors	400, 401, 403, 404, 500.
Notes	Metadata may be lazily extracted and cached.

GET /preview

Item	Details
Purpose	Preview a dataset version.
Auth	Service view; dataset view.
Parameters	Required query dataset, version; optional layer for file datasets.
Body	None.
Response	200 GeoJSON FeatureCollection for vectors/PostGIS; raster preview returns image/jpeg or image/png.
Status/Errors	400, 401, 403, 404, 422, 500.
Notes	layer is rejected for PostGIS datasets.

POST /register

Item	Details
Purpose	Compatibility stub.
Auth	Service edit.
Parameters	None.
Body	Ignored.
Response	200 empty response.
Status/Errors	401, 403.
Notes	No registration is performed.

Filter, dissolve, and clip

GET /datasets/{name}/versions/{version}/fields

Item	Details
Purpose	List fields for a spatial layer.
Auth	Service view; dataset view.
Parameters	Path name, version; optional query layer (first spatial layer by default).
Body	None.
Response	200 field metadata JSON.
Status/Errors	400, 401, 403, 404, 500.
Notes	File-backed spatial datasets only.

GET /datasets/{name}/versions/{version}/values

Item	Details
Purpose	List distinct values for a field.
Auth	Service view; dataset view.
Parameters	Path name, version; required query field; optional layer.
Body	None.
Response	200 values JSON, limited to 200 distinct values.
Status/Errors	400, 401, 403, 404, 500.
Notes	File-backed spatial datasets only.

POST /datasets/{name}/versions/{version}/filter

Item	Details
Purpose	Create a derived filtered version.
Auth	Service edit; dataset edit.
Parameters	Path name, version.
Body	JSON {layer, where}.
Response	200 {success,new_version}.
Status/Errors	400, 401, 403, 404, 409, 500.
Notes	Empty clauses and basic destructive SQL tokens are rejected.

POST /datasets/{name}/versions/{version}/dissolve

Item	Details
Purpose	Create a dissolved vector version.
Auth	Service edit; dataset edit.
Parameters	Path name, version.
Body	JSON {layer, mode:"all"|"field", field, aggregations}.
Response	200 {success,new_version}.
Status/Errors	400, 401, 403, 404, 409, 500.
Notes	field is required in field mode; aggregations are numeric sums.

POST /datasets/{name}/versions/{version}/clip

Item	Details
Purpose	Create a spatially clipped version.
Auth	Service edit; dataset edit; clip dataset view in dataset mode.
Parameters	Path name, version; optional query folder_id scopes lookup of clip_dataset in dataset mode.
Body	JSON mode (draw, bbox, dataset) with geometry, bbox, or clip_dataset; clip_layer may select a clip layer.
Response	200 {success,new_version}.
Status/Errors	400, 401, 403, 404, 409, 500.
Notes	Supply only the mode-appropriate clip input.

Dataset attribute editing

GET /datasets/{name}/versions/{version}/edit/capability

Item	Details
Purpose	Report editor backend and editability.
Auth	Service view; dataset view.
Parameters	Path name, version; optional query layer.
Body	None.
Response	200 capability JSON.
Status/Errors	400, 401, 403, 500.
Notes	Capability does not grant edit permission.

GET /datasets/{name}/versions/{version}/edit/schema

Item	Details
Purpose	Return editable column and identity schema.
Auth	Service view; dataset view.
Parameters	Path name, version; optional layer.
Body	None.
Response	200 schema with columns, PK/identity fields, and editable.
Status/Errors	400, 401, 403, 500.
Notes	Backend is resolved from the version.

GET /datasets/{name}/versions/{version}/edit/rows

Item	Details
Purpose	Page, sort, and filter attribute rows.
Auth	Service view; dataset view.
Parameters	Path name, version; optional layer, limit, offset, sort, order, filters.
Body	None.
Response	200 rows response with schema, rows, total, paging, and identity fields.
Status/Errors	400, 401, 403, 500.
Notes	See shared row-filter profile.

POST /datasets/{name}/versions/{version}/edit/update

Item	Details
Purpose	Update one attribute row.
Auth	Service edit; dataset edit.
Parameters	Path name, version; optional query layer.
Body	JSON {pk_column, pk_value, updates}.
Response	200 mutation result.
Status/Errors	400, 401, 403; 409 zero rows; 500.
Notes	Updates are restricted by editor schema.

POST /datasets/{name}/versions/{version}/edit/delete

Item	Details
Purpose	Delete one attribute row.
Auth	Service edit; dataset edit.
Parameters	Path name, version; optional layer.
Body	JSON {pk_column, pk_value}.
Response	200 mutation result.
Status/Errors	400, 401, 403; 409 zero rows; 500.
Notes	Deletes data in the resolved backend.

POST /datasets/{name}/versions/{version}/edit/insert

Item	Details
Purpose	Insert an attribute row.
Auth	Service edit; dataset edit.
Parameters	Path name, version; optional layer.
Body	JSON {row}.
Response	200 mutation result.
Status/Errors	400, 401, 403, 500.
Notes	Row keys must be editable columns.

PostgreSQL connections and tables

POST /api/connections/test

Item	Details
Purpose	Test PostgreSQL and PostGIS connectivity.
Auth	Intended service admin.
Parameters	None.
Body	JSON id or connection fields name, host, port, database_name, username, password, sslmode.
Response	200 {success,postgis,error?,postgres_version?,postgis_version?}.
Status/Errors	400, 401, 403, 404, 500, 503; connectivity failure is often 200 success:false.
Notes	Default port 5432; SSL modes: disable, require, verify-ca, verify-full.

GET /api/connections

Item	Details
Purpose	List saved PostgreSQL connections without passwords.
Auth	Intended service admin.
Parameters	None.
Body	None.
Response	200 array id, name, host, port, database_name, username, sslmode, optional created_at.
Status/Errors	401, 403, 500, 503.
Notes	See BASE_PATH ACL caveat.

POST /api/connections

Item	Details
Purpose	Create a PostgreSQL connection.
Auth	Intended service admin.
Parameters	None.
Body	JSON name, host, port, database_name, username, password, sslmode.
Response	201 {id}.
Status/Errors	400, 401, 403, 409, 500, 503.
Notes	Password is required.

PUT /api/connections/{id}

Item	Details
Purpose	Update a PostgreSQL connection.
Auth	Intended service admin.
Parameters	Path id.
Body	Same connection JSON; blank password retains the old password.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	Default port 5432.

DELETE /api/connections/{id}

Item	Details
Purpose	Delete a saved PostgreSQL connection.
Auth	Intended service admin.
Parameters	Path id.
Body	None.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	Does not delete the remote database.

GET /api/connections/{id}/tables

Item	Details
Purpose	List spatial tables in a connection.
Auth	Intended service admin.
Parameters	Path id.
Body	None.
Response	200 array f_table_schema, f_table_name, f_geometry_column, srid, type.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	Blocked schemas are omitted.

GET /api/connections/{id}/table/{table}/schema

Item	Details
Purpose	Return PostGIS table editor schema.
Auth	Intended service admin; dataset view when table is registered.
Parameters	Path id, table; optional query schema (default public).
Body	None.
Response	200 editor schema.
Status/Errors	400, 401, 403, 500, 503.
Notes	Unregistered tables have no dataset ACL check.

GET /api/connections/{id}/table/{table}/rows

Item	Details
Purpose	Page PostGIS table rows.
Auth	Intended service admin; dataset view when registered.
Parameters	Path id, table; query schema, limit, offset, sort, order, filters.
Body	None.
Response	200 rows response.
Status/Errors	400, 401, 403, 500, 503.
Notes	See shared row-filter profile.

GET /api/connections/{id}/table/{table}/preview

Item	Details
Purpose	Preview a PostGIS table as WGS84 GeoJSON.
Auth	Intended service admin; current login; dataset view when registered.
Parameters	Path id, table; optional schema (default public), geometry_column.
Body	None.
Response	200 GeoJSON FeatureCollection.
Status/Errors	400, 401, 403, 422, 500, 503.
Notes	Schema/table identifiers are validated.

POST /api/table/update

Item	Details
Purpose	Update a row in a connected PostGIS table.
Auth	Service edit; dataset edit when registered.
Parameters	None.
Body	JSON {connection_id, schema, table, pk_column, pk_value, updates}.
Response	200 mutation result.
Status/Errors	400, 401, 403; 409 zero rows; 500, 503.
Notes	schema defaults to public.

POST /api/table/delete

Item	Details
Purpose	Delete a row from a connected PostGIS table.
Auth	Service edit; dataset edit when registered.
Parameters	None.
Body	JSON {connection_id, schema, table, pk_column, pk_value}.
Response	200 mutation result.
Status/Errors	400, 401, 403; 409 zero rows; 500, 503.
Notes	schema defaults to public.

POST /api/table/insert

Item	Details
Purpose	Insert a row into a connected PostGIS table.
Auth	Service edit; dataset edit when registered.
Parameters	None.
Body	JSON {connection_id, schema, table, row}.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 500, 503.
Notes	row is required; schema defaults to public.

POST /api/datasets/register

Item	Details
Purpose	Register an existing PostGIS table as a GeoVault dataset.
Auth	Service edit; current login.
Parameters	Optional query folder_id; body folder_id takes precedence when positive.
Body	JSON name, connection_id, schema_name, table_name, geometry_column, project_id, folder_id.
Response	201 registration/Version result.
Status/Errors	400, 401, 403, 404, 409, 500, 503.
Notes	schema_name defaults to public; project_id defaults to 1.

Database services

GET /api/database-services

Item	Details
Purpose	List password-free pg_service entries from QGIS publish service.
Auth	Intended service admin.
Parameters	None.
Body	None.
Response	200 array name, host, port, dbname, user, optional sslmode.
Status/Errors	401, 403, 502.
Notes	Passwords are never returned.

POST /api/database-services/{name}/open

Item	Details
Purpose	Resolve/synchronize a database service into pg_connections.
Auth	Intended service admin.
Parameters	Path name.
Body	None.
Response	200 {success,connection_id,pg_service_name,host,port,dbname}.
Status/Errors	400, 401, 403, 404, 502, 503.
Notes	Upstream service must contain a password.

PostGIS service proxy

GET /api/postgis-service/connections

Item	Details
Purpose	Proxy the PostGIS Service connection registry.
Auth	Service view; caller session forwarded upstream.
Parameters	None.
Body	None.
Response	Upstream JSON/status.
Status/Errors	401, 403, 502, upstream errors.
Notes	Default upstream is http://127.0.0.1:8090/postgis-service.

GET /api/postgis-service/databases

Item	Details
Purpose	Proxy the PostGIS Service database list.
Auth	Service view; caller session forwarded.
Parameters	Optional query connection_id.
Body	None.
Response	Upstream JSON/status.
Status/Errors	401, 403, 502, upstream errors.
Notes	Response schema is owned by PostGIS Service.

POST /api/postgis-service/databases

Item	Details
Purpose	Proxy database creation to PostGIS Service.
Auth	Service edit; current login; caller session forwarded.
Parameters	None.
Body	JSON is passed through unchanged; GeoVault does not define its fields.
Response	Upstream JSON/status.
Status/Errors	400, 401, 403, 502, upstream errors.
Notes	No undocumented body fields are asserted here.

GET /api/postgis-service/discover

Item	Details
Purpose	Discover registry connections/databases available to GeoVault.
Auth	Service view.
Parameters	None.
Body	None.
Response	200 {connections:[...]} registry discovery tree.
Status/Errors	401, 403, 500, 503.
Notes	Reads the shared registry in the GeoVault database.

POST /api/postgis-service/adopt

Item	Details
Purpose	Adopt a registry database as a GeoVault PostgreSQL connection.
Auth	Service edit; current login.
Parameters	None.
Body	JSON {connection_id, database_id, name}.
Response	200 or 201 {connection_id,name,existing}.
Status/Errors	400, 401, 403, 409, 500, 503.
Notes	database_id is required; name can be generated.

GET /api/postgis-service/connections/{id}/pg-users

Item	Details
Purpose	Proxy PostgreSQL users for a registry connection.
Auth	Service view; caller session forwarded.
Parameters	Path id.
Body	None.
Response	Upstream JSON/status.
Status/Errors	400, 401, 403, 502, upstream errors.
Notes	Response schema is owned upstream.

GET /api/postgis-service/databases/{id}/schemas

Item	Details
Purpose	Proxy schemas for a registry database.
Auth	Service view; caller session forwarded.
Parameters	Path id.
Body	None.
Response	Upstream JSON/status.
Status/Errors	400, 401, 403, 502, upstream errors.
Notes	Response schema is owned upstream.

GET /api/postgis-service/databases/{id}/tables

Item	Details
Purpose	Proxy tables for a registry database.
Auth	Service view; caller session forwarded.
Parameters	Path id; optional query schema.
Body	None.
Response	Upstream JSON/status.
Status/Errors	400, 401, 403, 502, upstream errors.
Notes	Response schema is owned upstream.

Quick import and ESRI

POST /api/quick-import

Item	Details
Purpose	Import directly into PostGIS without adding a GeoVault catalog dataset.
Auth	Service edit; current login.
Parameters	None.
Body	JSON: source_type (url,s3,esri,geoserver,postgis), source-specific fields url; s3_bucket, s3_key, s3_endpoint, s3_region, s3_access_key, s3_secret_key, s3_path_style; esri_service_url, esri_username, esri_password, esri_token, esri_layer_ids, esri_prefix; geoserver_connection_id, geoserver_workspace, geoserver_layer; source_database_id, source_schema, source_tables; plus schema, table_name, mode and PostGIS sidecar destination fields. Multipart supports upload only with file, source_type, schema, table_name, mode, and destination fields.
Response	201 {success,source_type,database_id,tables,schema,pg_service}.
Status/Errors	400, 401, 403, 422, 500, 503.
Notes	source_type=upload is multipart; JSON URL/S3 downloads are temporary.

POST /api/esri/service/browse

Item	Details
Purpose	Inspect an ArcGIS FeatureServer/MapServer and obtain layer metadata.
Auth	Service edit; current login.
Parameters	None.
Body	JSON {service_url, username, password}.
Response	200 {service:{service_url,service_type,layers:[{id,name,type,geometry_type,supports_query,max_record_count,layer_url}]},token}.
Status/Errors	400, 401, 403, upstream/network errors represented as 400.
Notes	Username/password are optional for public services.

POST /api/esri/import

Item	Details
Purpose	Import selected ArcGIS layers to PostGIS and register datasets.
Auth	Service edit; current login.
Parameters	Optional query folder_id; body folder_id takes precedence when positive.
Body	JSON service_url, username, password, token, layer_ids, postgis_destination (existing or new), postgis_database_id, postgis_connection_id, postgis_new_database_name, schema, dataset_prefix, run_as_background_job, folder_id.
Response	202 queued/completed job record.
Status/Errors	400, 401, 403, 500, 503.
Notes	Existing destination requires database ID; new requires connection ID and database name.

GET /api/esri/jobs/{id}

Item	Details
Purpose	Read an ESRI import job status.
Auth	Service view.
Parameters	Path id.
Body	None.
Response	200 stored job record.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	ESRI jobs share the GeoServer jobs storage table.

GeoServer administration, catalog, styles, publish, and jobs

GET /api/geoserver/connections

Item	Details
Purpose	List GeoServer connections without passwords.
Auth	Service view; metadata database required.
Parameters	None.
Body	None.
Response	200 array of public connection records.
Status/Errors	401, 403, 500, 503.
Notes	Passwords are not returned.

POST /api/geoserver/connections

Item	Details
Purpose	Create a GeoServer connection.
Auth	Service edit.
Parameters	None.
Body	JSON name, url, username, password, default_workspace, enabled, verify_ssl.
Response	201 {id}.
Status/Errors	400, 401, 403, 409, 500, 503.
Notes	Name, URL, username, and password are required.

PUT /api/geoserver/connections/{id}

Item	Details
Purpose	Update a GeoServer connection.
Auth	Service edit.
Parameters	Path id.
Body	Same fields; blank password retains the stored password.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	enabled and verify_ssl default true when omitted.

DELETE /api/geoserver/connections/{id}

Item	Details
Purpose	Delete a GeoServer connection.
Auth	Service edit.
Parameters	Path id.
Body	None.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 500, 503.
Notes	Does not alter the remote GeoServer.

POST /api/geoserver/connections/{id}/test

Item	Details
Purpose	Test a stored GeoServer connection.
Auth	Service edit.
Parameters	Path id.
Body	None.
Response	200 {success,url,workspaces?,error?}.
Status/Errors	400, 401, 403, 404, 500, 503; remote failure can be 200 success:false.
Notes	Counts accessible workspaces on success.

GET /api/geoserver/workspaces

Item	Details
Purpose	List GeoServer workspaces.
Auth	Service view.
Parameters	Required query connection_id.
Body	None.
Response	200 workspace array.
Status/Errors	400, 401, 403, 404, 500, 502.
Notes	Data comes from the selected GeoServer.

POST /api/geoserver/workspaces

Item	Details
Purpose	Create a GeoServer workspace.
Auth	Service edit.
Parameters	None.
Body	JSON {connection_id, name, recurse}; recurse is accepted but unused for creation.
Response	201 {"success":true}.
Status/Errors	400, 401, 403, 502.
Notes	connection_id and name are required.

DELETE /api/geoserver/workspaces/{name}

Item	Details
Purpose	Delete a GeoServer workspace.
Auth	Service edit.
Parameters	Path name; required query connection_id; optional recurse=true.
Body	None.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 502.
Notes	Recursive deletion is forwarded to GeoServer.

GET /api/geoserver/catalog

Item	Details
Purpose	Read workspaces, layers, styles, and datastores from GeoServer.
Auth	Service view.
Parameters	Required query connection_id.
Body	None.
Response	200 {connection,workspaces,layers,styles,datastores}.
Status/Errors	400, 401, 403, 502.
Notes	Datastore lookup failures for individual workspaces are omitted.

POST /api/geoserver/catalog/import

Item	Details
Purpose	Register a remote GeoServer catalog layer as a GeoVault dataset.
Auth	Service edit; current login.
Parameters	Optional query folder_id; body folder_id takes precedence when positive.
Body	JSON {connection_id, workspace, layer_name, dataset_name, folder_id}.
Response	201 {dataset,type,wms_url,datasource_type}.
Status/Errors	400, 401, 403, 502, 500, 503.
Notes	Dataset name defaults to lowercased workspace_layer.

GET /api/geoserver/styles

Item	Details
Purpose	List GeoServer styles.
Auth	Service view.
Parameters	Required query connection_id.
Body	None.
Response	200 style array.
Status/Errors	400, 401, 403, 502.
Notes	Remote GeoServer response.

POST /api/geoserver/styles

Item	Details
Purpose	Upload an SLD style.
Auth	Service edit.
Parameters	None.
Body	JSON {connection_id, style_name, sld} or multipart connection_id, style_name, required file.
Response	201 {"success":true}.
Status/Errors	400, 401, 403, 502.
Notes	Multipart SLD file is limited to 2 MiB read size.

POST /api/geoserver/styles/assign

Item	Details
Purpose	Assign a style to a GeoServer layer.
Auth	Service edit.
Parameters	None.
Body	JSON {connection_id, workspace, layer_name, style_name}.
Response	200 {"success":true}.
Status/Errors	400, 401, 403, 404, 502.
Notes	All fields are required.

GET /api/geoserver/styles/{name}

Item	Details
Purpose	Download a style's SLD XML.
Auth	Service view.
Parameters	Path name; required query connection_id.
Body	None.
Response	200 application/xml.
Status/Errors	400, 401, 403, 502.
Notes	Raw SLD bytes are returned.

POST /api/geoserver/publish

Item	Details
Purpose	Publish an existing local GeoVault version to GeoServer.
Auth	Service edit; dataset edit.
Parameters	None.
Body	JSON dataset_name, version, publish_to_geoserver, geoserver_connection_id, geoserver_workspace, geoserver_store_name, geoserver_layer_name, geoserver_style, geoserver_publish_immediate.
Response	202 queued publish result with job ID/status.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	Requires a local file; publish_to_geoserver must be true.

GET /api/geoserver/jobs/{id}

Item	Details
Purpose	Read a GeoServer publish job status.
Auth	Service view.
Parameters	Path id.
Body	None.
Response	200 stored job record.
Status/Errors	400, 401, 403, 404, 500, 503.
Notes	Job status is persisted in the metadata database.

GET /api/datasets/{name}/geoserver-publications

Item	Details
Purpose	List recorded GeoServer publications for a dataset.
Auth	Service view; metadata database required.
Parameters	Path name.
Body	None.
Response	200 publication-record array.
Status/Errors	401, 403, 500, 503.
Notes	The handler does not perform an additional dataset ACL check.

Coverage

This document contains 92 method/path operations across 81 unique paths, matching the OpenAPI inventory and the API/data classification of routes registered in main.go registerRoutes (including POST /register and GET /datasets/{name}).