Site: Planekeeper Docs — Monitor software versions across your stack. Planekeeper tracks releases, gathers version data, and alerts on drift.
Section: Reference > API reference
Source: https://docs.planekeeper.com/reference/api/
Title: API reference
Author: Planekeeper
Description: Interactive API documentation, OpenAPI specs, and how to authenticate requests via Swagger UI.
Word count: 529
Reading time: 3 min

Contents:
- [Swagger UI](#swagger-ui)
  - [Selecting a server](#selecting-a-server)
  - [Authenticating in Swagger UI](#authenticating-in-swagger-ui)
- [OpenAPI spec files](#openapi-spec-files)
- [Generating a bundled spec](#generating-a-bundled-spec)
- [API structure](#api-structure)
  - [Authentication](#authentication)
  - [Common endpoints](#common-endpoints)

***

# API reference


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`](https://www.planekeeper.com/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:

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

All subsequent requests will include your API key. See [API keys](https://docs.planekeeper.com/reference/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`](https://www.planekeeper.com/api/spec/openapi-client.yaml) | Organization-scoped endpoints |
| **Shared Paths** | [`/api/spec/openapi-shared.yaml`](https://www.planekeeper.com/api/spec/openapi-shared.yaml) | Shared path definitions |
| **Schemas** | [`/api/spec/components/schemas.yaml`](https://www.planekeeper.com/api/spec/components/schemas.yaml) | Request/response schemas |
| **Parameters** | [`/api/spec/components/parameters.yaml`](https://www.planekeeper.com/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](#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](https://redocly.com/docs/cli/):

```bash
# 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](https://openapi-generator.tech/) or [oapi-codegen](https://github.com/oapi-codegen/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](https://docs.planekeeper.com/reference/api-keys/) for details on key creation and management.

### Common endpoints

For a complete list of endpoints, parameters, and schemas, open the [Swagger UI](https://www.planekeeper.com/api/v1/swagger). 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`)


---

## Related

- Next: [Cron expressions](https://docs.planekeeper.com/reference/cron-expressions/page.md) — Cron expression format reference for scheduling gather and scrape jobs, with common examples and tips for choosing intervals.
- Section: [Reference](https://docs.planekeeper.com/reference/index.md)