API Reference

DroneDB Registry exposes a REST API for programmatic access to all features. All endpoints return JSON unless otherwise specified.

Interactive Documentation

Access the interactive API documentation at /scalar/v1 on your Registry instance (e.g., hub.dronedb.app/scalar/v1).

Authentication

Most endpoints require JWT authentication. Obtain a token via the authenticate endpoint:

POST /users/authenticate
Content-Type: application/json

{
  "userName": "admin",
  "password": "password123"
}

Use the token in subsequent requests:

Authorization: Bearer <token>

Tokens can be refreshed before expiration:

POST /users/authenticate/refresh
Authorization: Bearer <token>

Organizations

Base Route: /orgs

Method	Endpoint	Description
GET	/orgs	List all organizations
GET	/orgs/public	List public organizations (no auth required)
GET	/orgs/{orgSlug}	Get organization details
POST	/orgs	Create organization
PUT	/orgs/{orgSlug}	Update organization
DELETE	/orgs/{orgSlug}	Delete organization

Datasets

Base Route: /orgs/{orgSlug}/ds

Method	Endpoint	Description
GET	/orgs/{orgSlug}/ds	List all datasets in organization
GET	/orgs/{orgSlug}/ds/{dsSlug}	Get dataset entries
GET	/orgs/{orgSlug}/ds/{dsSlug}/ex	Get extended dataset info
GET	/orgs/{orgSlug}/ds/{dsSlug}/stamp	Get dataset checksum and metadata
POST	/orgs/{orgSlug}/ds	Create dataset
PUT	/orgs/{orgSlug}/ds/{dsSlug}	Update dataset
DELETE	/orgs/{orgSlug}/ds/{dsSlug}	Delete dataset
POST	/orgs/{orgSlug}/ds/{dsSlug}/rename	Rename dataset
POST	/orgs/{orgSlug}/ds/{dsSlug}/chattr	Change attributes (visibility)

Objects

Base Route: /orgs/{orgSlug}/ds/{dsSlug}

Listing & Searching

Method	Endpoint	Description
GET	.../list?path=	List objects at path
POST	.../list	List objects (POST version)
POST	.../search	Search objects in dataset
GET	.../obj?path=	Get object info

Upload & Modification

Method	Endpoint	Description
POST	.../obj	Upload object (multipart form)
PUT	.../obj	Move/rename object
DELETE	.../obj?path=	Delete object
DELETE	.../obj/batch	Delete multiple objects

Download

Method	Endpoint	Description
GET	.../download?path=	Download object(s)
POST	.../download	Download objects (POST version)
GET	.../ddb	Download DroneDB index file

Visualization

Method	Endpoint	Description
GET	.../thumb?path=	Generate thumbnail
GET	.../tiles/{tz}/{tx}/{ty}.png	Generate map tile
GET	.../build/{hash}/*	Get build files (COG, NXS, EPT)

Build Jobs

Method	Endpoint	Description
POST	.../build	Start build job for object
GET	.../builds	List build jobs (paginated)
POST	.../builds/clear	Clear completed build jobs

Tasks (Processing Platform)

Base Route: /orgs/{orgSlug}/ds/{dsSlug}/tasks

See the Processing Platform page for full documentation, tool reference, and examples.

Method	Endpoint	Description
GET	.../tasks/tools	List available tools with JSON Schema
POST	.../tasks	Submit a new task (202) or get dedup hit (200)
GET	.../tasks	List tasks (?toolId=&state=&skip=0&take=50)
POST	.../tasks/clear	Delete all terminal tasks (?toolId= optional filter)
GET	.../tasks/{id}	Get full task status, progress, log tail, artifact
GET	.../tasks/{id}/log	Incremental log (?since={cursor})
GET	.../tasks/{id}/result	Download task artifact (range requests supported)
DELETE	.../tasks/{id}	Cancel or mark task as Deleted

Share

Base Route: /share

The Share API enables file uploads via the DroneDB CLI (ddb share).

Method	Endpoint	Description
POST	/share/init	Initialize share session
GET	/share/{token}	Get share batch info
POST	/share/{token}/upload	Upload file to share
POST	/share/{token}/upload/chunked	Upload large file in chunks
POST	/share/{token}/commit	Finalize share
POST	/share/{token}/rollback	Cancel share

POST /share/init body fields:

Field	Type	Description
tag	string	Full org/dataset tag for the destination dataset (optional).
orgSlug	string	Destination organization slug. When tag is omitted, the dataset slug is auto-generated.
datasetName	string	Human-readable dataset name (optional).

Push

Base Route: /orgs/{orgSlug}/ds/{dsSlug}/push

The Push API enables syncing local datasets to Registry via the DroneDB CLI (ddb push).

Method	Endpoint	Description
POST	.../push/init	Initialize push operation
POST	.../push/upload	Upload file during push
POST	.../push/meta	Upload metadata
POST	.../push/commit	Finalize push

Metadata

Base Route: /orgs/{orgSlug}/ds/{dsSlug}/meta

Method	Endpoint	Description
GET	.../meta/list	List all metadata keys
GET	.../meta/{key}	Get metadata values by key
POST	.../meta/{key}	Add metadata entry
POST	.../meta/{key}/set	Set/replace metadata
DELETE	.../meta/{key}	Remove all metadata with key
DELETE	.../meta/{id}	Remove specific metadata entry
POST	.../meta/dump	Export all metadata

Users

Base Route: /users

Authentication

Method	Endpoint	Description
POST	/users/authenticate	Login (returns JWT)
POST	/users/authenticate/refresh	Refresh JWT token

User Management (Admin)

Method	Endpoint	Description
GET	/users	List all users
GET	/users/detailed	List users with extended info
POST	/users	Create user
PUT	/users/{userName}	Update user
DELETE	/users/{userName}	Delete user

Password Management

Method	Endpoint	Description
POST	/users/changepwd	Change current user password
PUT	/users/{userName}/changepwd	Change user password (admin)

Roles

Method	Endpoint	Description
GET	/users/roles	List all roles
POST	/users/roles/{roleName}	Create role (admin)
DELETE	/users/roles/{roleName}	Delete role (admin)

Storage & Metadata

Method	Endpoint	Description
GET	/users/storage	Get current user storage info
GET	/users/{userName}/storage	Get user storage info (admin)
GET	/users/{userName}/meta	Get user metadata
POST	/users/{userName}/meta	Set user metadata (admin)

Organizations

Method	Endpoint	Description
GET	/users/{userName}/orgs	Get user's organizations
PUT	/users/{userName}/orgs	Set user's organizations (admin)

STAC

The STAC (SpatioTemporal Asset Catalog) API provides standardized access to public datasets.

Method	Endpoint	Description
GET	/stac	Root STAC Catalog
GET	/orgs/{orgSlug}/ds/{dsSlug}/stac	Dataset STAC Collection

Browse STAC catalogs with tools like STAC Browser.

System

Base Route: /sys

Method	Endpoint	Description
GET	/sys/version	Get Registry version
GET	/sys/features	Get active feature flags and platform catalog (no auth required)
GET	/sys/build-pending-status	Get background build job status
GET	/sys/tasks	List tasks across all users and datasets (admin only) (?toolId=&state=&userId=&skip=0&take=50)
POST	/sys/import-dataset	Import dataset from another Registry
POST	/sys/import-organization	Import organization from another Registry
POST	/sys/move-datasets	Move datasets between organizations (admin, enforced server-side)
POST	/sys/merge-organizations	Merge one organization into another (admin, enforced server-side)
POST	/sys/cleanupbatches	Purge expired or orphaned upload batches
POST	/sys/cleanupdatasets	Remove empty dataset records
POST	/sys/migratevisibility	Migrate dataset visibility from legacy format
POST	/sys/cleanup-jobindices	Purge old job index records (optional ?retentionDays=N)
POST	/sys/cleanup	Run DroneDB cleanup on every dataset (admin only, async)
POST	/sys/check-artifact-completeness	Scan all datasets and enqueue rebuilds for incomplete build artifacts (admin only, async)

GET /sys/features response fields

This endpoint is available without authentication and is used by the Hub frontend to discover platform capabilities.

Field	Type	Description
organizationMemberManagement	bool	Whether org-level member management is enabled
userManagement	bool	Whether local user management is enabled (false when external auth is configured)
storageLimiter	bool	Whether per-user storage limiting is enabled
maxConcurrentDownloadsPerUser	int?	Concurrent download limit per user (null = unlimited)
disableAnonymousBulkDownloads	bool	Whether anonymous bulk archive downloads are blocked
passwordPolicy	object?	Active password complexity policy, or null
datasetThumbnailCandidates	string[]	Ordered list of dataset thumbnail file name candidates
maxExportSizeBytes	long?	Maximum raster export size in bytes (null = unlimited)
bulkDownloadAsyncThresholdBytes	long	Selection size threshold above which bulk downloads are routed to the async task
taskTools	array	Catalog of available task tools (id, version, title, required access, artifact flag, extension)
taskStates	array	Task state machine with {state, isTerminal} per entry
hubOptions	object?	Hub UI branding and feature flags
hubVersion	string?	Semver of the Hub (Vue SPA) currently deployed
registryVersion	string?	Registry backend assembly version
ddbVersion	string?	Native DroneDB library version

Health Checks

Endpoint	Description
/version	Application version (no auth)
/quickhealth	Basic health check (requires auth)
/health	Full health check (requires auth)

Error Responses

API errors return JSON with the following structure:

{
  "error": "Error message description"
}

Common HTTP status codes:

• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (missing or invalid token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 500 - Internal Server Error