View Reference →

🔐 Token-Based Access All API requests require a valid Bearer token. Generate tokens via the Dashboard or OAuth2 flow. Tokens expire after 24 hours and support fine-grained scopes.

Authorization Header

HTTP Request

GET /v2/layers HTTP/1.1
Host: api.geoserver.dev
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json
                    

Token Scopes

Scope	Description
layers:read	Access layer metadata and render tiles
layers:write	Create, update, or delete vector/raster layers
styles:manage	Upload or modify SLD/SE style definitions
admin:full	Workspace, database, and user management

GET /v2/workspaces/{workspace}/layers

Retrieve a paginated list of all layers within a specified workspace. Supports filtering by type, bbox, and last modified date.

Parameter	Type	Required	Description
workspace	string	YES	Workspace identifier (e.g., `nasa_earth`)
limit	integer		Max results per page (default: 50, max: 200)
offset	integer		Page offset for pagination
type	enum		Filter by `vector`, `raster`, or `tile`

Response (200 OK)
{
  "data": [
    {
      "id": "lyr_9x8k2m4p",
      "name": "global_coastlines",
      "type": "vector",
      "crs": "EPSG:4326",
      "features_count": 14829,
      "updated_at": "2025-08-12T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "has_next": true
  }
}

POST /v2/features/{layer_id}/upload

Batch ingest spatial features. Supports GeoJSON, Shapefile, and GPKG formats. Auto-detects CRS and creates spatial indexes.

Request Body (Multipart)

--boundary_7a9f2
Content-Disposition: form-data; name="file"; filename="buildings.geojson"

{
  "type": "FeatureCollection",
  "features": [...]
}
--boundary_7a9f2--

GeoJSON Feature Schema

All vector layers conform to RFC 7946. Custom properties are stored in the properties object and indexed for fast filtering.

Feature Template
{
  "type": "Feature",
  "id": "feat_uuid_v4",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[...]]
  },
  "properties": {
    "land_use": "residential",
    "area_sqm": 4520.5,
    "verified": true
  }
}

Supported CRS Authorities

Authority	Format	Notes
EPSG	Standard	Primary coordinate system reference
ESRI	Proprietary	Auto-translated to EPSG equivalents
OGC:CRS84	Lat/Lon	Recommended for web mapping

HTTP & Application Errors

GeoServer uses standard HTTP status codes alongside structured JSON error payloads for programmatic handling.

Code	Message	Resolution
400	Invalid CRS or malformed geometry	Validate GeoJSON structure
401	Missing or expired token	Refresh authentication
403	Insufficient scope for resource	Check workspace permissions
422	SRID mismatch during ingest	Explicitly set `crs` param
429	Rate limit exceeded	Implement exponential backoff
503	Spatial index rebuilding	Retry after `Retry-After` header