API reference

Interactive API documentation, OpenAPI specs, and how to authenticate requests via Swagger UI.

Planekeeper exposes a REST API documented with OpenAPI 3.0. You can explore and test endpoints interactively using the built-in Swagger UI, or download the OpenAPI spec files for use with code generators and API clients.

Swagger UI

The API server hosts Swagger UI for interactive exploration and testing.

API	Swagger UI URL	Description
Client API	`/api/v1/swagger`	Organization-scoped operations (jobs, rules, alerts, notifications)

Open the Swagger UI in your browser to browse all available endpoints, view request/response schemas, and send test requests directly from the page.

Selecting a server

The Swagger UI includes a server dropdown at the top of the page. You can switch between:

Production — sends requests to https://www.planekeeper.com
Current Host — sends requests to whatever host is serving the Swagger UI (useful for local development)

Authenticating in Swagger UI

To make authenticated requests from Swagger UI:

Click the Authorize button (lock icon) at the top of the page
Enter your API key in the apiKey field using the format: pk_<id>_<secret>
Click Authorize, then Close

All subsequent requests will include your API key. See API keys for details on creating and managing keys.

OpenAPI spec files

The raw OpenAPI specification files are served by the API server and can be downloaded directly:

Spec	URL	Description
Client API	`/api/spec/openapi-client.yaml`	Organization-scoped endpoints
Shared Paths	`/api/spec/openapi-shared.yaml`	Shared path definitions
Schemas	`/api/spec/components/schemas.yaml`	Request/response schemas
Parameters	`/api/spec/components/parameters.yaml`	Shared query and path parameters

info

Multi-file spec

The Client API spec uses $ref to reference shared paths, schemas, and parameters across multiple files. Most tools (Postman, code generators) require a single self-contained file. See Generating a bundled spec below to combine everything into one file.

Generating a bundled spec

The Client API spec is split across several files. To produce a single self-contained YAML file you can import into Postman, Insomnia, or a code generator, use Redocly CLI:

# Install Redocly CLI
npm install -g @redocly/cli

# Download the spec files
curl -O https://www.planekeeper.com/api/spec/openapi-client.yaml
curl -O https://www.planekeeper.com/api/spec/openapi-shared.yaml
mkdir -p components
curl -o components/schemas.yaml https://www.planekeeper.com/api/spec/components/schemas.yaml
curl -o components/parameters.yaml https://www.planekeeper.com/api/spec/components/parameters.yaml
curl -o components/responses.yaml https://www.planekeeper.com/api/spec/components/responses.yaml
curl -o components/securitySchemes.yaml https://www.planekeeper.com/api/spec/components/securitySchemes.yaml

# Bundle into a single file
redocly bundle openapi-client.yaml -o planekeeper-api.yaml

The resulting planekeeper-api.yaml is a single file with all $ref entries resolved. Use it with:

Code generators — openapi-generator or oapi-codegen
API clients — import into Postman, Insomnia, or Bruno
Documentation — generate custom API docs with Redoc or similar tools

API structure

All client-facing endpoints are served under the /api/v1/client base path.

Authentication

All API requests require authentication. Pass your API key in the X-API-Key header:

X-API-Key: pk_<id>_<secret>

See API keys for details on key creation and management.

Common endpoints

For a complete list of endpoints, parameters, and schemas, open the Swagger UI. Key endpoint groups include:

Gather Jobs — manage upstream release tracking (/gather-jobs)
Scrape Jobs — manage repository version scraping (/scrape-jobs), including POST /scrape-jobs/{id}/set-version to manually set the deployed version for manual scrape jobs
Rules — configure monitoring rules (/rules)
Alert Configs — link jobs to rules (/alert-configs)
Alerts — view and acknowledge alerts (/alerts)
Notification Channels — configure webhook endpoints (/notification-channels)
Notification Rules — route alerts to channels (/notification-rules)
Releases — browse upstream release data (/releases)
Versions — browse scraped version data (/versions)