GeoServer REST API

Welcome to the GeoServer API documentation. This RESTful interface allows you to programmatically manage geospatial data, map layers, styles, and workspaces. All requests use standard HTTP methods and return JSON responses.

                    CURL
                    curl -X GET \n
                      https://api.geoserver.dev/v1/layers \n
                      -H "Authorization: Bearer <TOKEN>"
                

Authentication

Access to the GeoServer API requires an API key or OAuth 2.0 Bearer token. Include your credentials in the `Authorization` header for every request.

                    Header
                    Authorization: Bearer sk_live_4eC39HqLyjWDarjtT1zdp7dc
                

For API keys, use the format `X-API-Key: YOUR_KEY`. Tokens expire after 24 hours and must be refreshed via the `/auth/refresh` endpoint.

Base URL & HTTP Methods

All API requests are made against the base URL below. Standard HTTP methods are used to perform CRUD operations on resources.

                    Base
                    https://api.geoserver.dev/v1
                

Method	Usage
GET	Retrieve resources
POST	Create new resources
PUT	Update existing resources
DELETE	Remove resources

Layers

Manage geospatial data layers, including shapefiles, GeoJSON, and raster formats.

GET /layers

Returns a paginated list of all active layers in your workspace.

Parameter	Type	Required	Description
workspace	string	Optional	Filter by workspace name
limit	integer	Optional	Max items to return (default: 50)
offset	integer	Optional	Pagination offset

                                JSON
{
  "data": [
    {
      "id": "lyr_8f3k21",
      "name": "global_cities_osm",
      "type": "vector",
      "format": "geojson",
      "crs": "EPSG:4326",
      "created_at": "2024-11-15T08:32:11Z"
    }
  ],
  "meta": {
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}
                            

POST /layers

Create a new layer by uploading a spatial dataset or referencing a remote URL.

                            JSON Body
{
  "name": "coastlines_global",
  "workspace": "maritime",
  "source_type": "upload",
  "format": "geojson",
  "srs": "EPSG:3857",
  "metadata": {
    "title": "Global Coastlines",
    "attribution": "NOAA / GeoServer"
  }
}
                        

Maps

Composite map layers that combine multiple data sources into a single rendered view.

GET /maps

List all configured map composites. Supports filtering by workspace and rendering engine.

                            Response
{
  "data": [
    {
      "id": "map_9x2m11",
      "name": "urban_planning_view",
      "layers": ["lyr_8f3k21", "lyr_4a2b88", "lyr_1c9d00"],
      "renderer": "vector-tiles",
      "bbox": [-180, -90, 180, 90]
    }
  ]
}
                        

Styles

Manage SLD/SE styling rules applied to vector and raster layers.

PUT /styles/{style_id}

Update an existing style definition. Accepts SLD XML or JSON schema.

                            JSON Body
{
  "title": "Highway Major Roads",
  "format": "sld",
  "xml": "...",
  "apply_to": ["vector"]
}
                        

Workspaces

Isolated environments for organizing layers, maps, and styles by project or client.

DELETE /workspaces/{workspace_id}

Permanently delete a workspace and all associated resources. This action is irreversible.

                            Response
{
  "status": "success",
  "message": "Workspace 'legacy_project' and 14 resources deleted."
}
                        

Error Codes

GeoServer uses standard HTTP status codes. Detailed error information is returned in the response body.

Code	Meaning	Description
400	Bad Request	Malformed request syntax or invalid parameters
401	Unauthorized	Missing or invalid API key/token
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource does not exist or is deleted
429	Rate Limit	Too many requests in a given timeframe
500	Server Error	Unexpected failure in geospatial processing

Rate Limits

API requests are limited to 1,000 requests per minute for standard plans and 10,000 for enterprise. Exceeding limits returns a `429` status with a `Retry-After` header.

                    Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1698765432
                