PatchVault Info

Patchvault API

A read-only JSON API over the public Patchvault catalog: lodges, councils, camps, sections, and their issues. Everything the API serves is data any visitor can already see on the website; collection contents, prices, and private notes are never exposed.

Authentication

Every request needs a personal API key passed as a bearer token. API keys are a Pro feature — create and revoke them from your profile settings (Edit profile → API). Keys start with pv_ and are shown once at creation.

curl -H "Authorization: Bearer pv_YOUR_KEY" \
  https://patchvault.org/api/v1/lodges

Requests without a valid key receive 401 Unauthorized with a JSON error body.

Identifiers

Every record is identified by its slug — the same identifier used in the website's URLs. Numeric database IDs never appear in the API and will never be accepted by it. Issues are keyed by their PatchVault catalog-entry slug (e.g. netopalis-1-f1), matching the web issue pages. If an issue is renumbered, its old slug keeps resolving, but the slug and url fields in every response are always the canonical current values — update any stored slugs from the response.

Endpoints

All endpoints are GET and return application/json.

Method	Path	Description
`GET`	`/api/v1/lodges/{lodge_slug}/issues`	List a lodge's issues (paginated)
`GET`	`/api/v1/lodges/{lodge_slug}/issues/{slug}`	Fetch one issue by catalog-entry slug
`GET`	`/api/v1/lodges`	List lodges (paginated)
`GET`	`/api/v1/lodges/{slug}`	Fetch one lodge by slug
`GET`	`/api/v1/councils/{council_slug}/issues`	List a council's issues (paginated)
`GET`	`/api/v1/councils/{council_slug}/issues/{slug}`	Fetch one issue by catalog-entry slug
`GET`	`/api/v1/councils`	List councils (paginated)
`GET`	`/api/v1/councils/{slug}`	Fetch one council by slug
`GET`	`/api/v1/camps/{camp_slug}/issues`	List a camp's issues (paginated)
`GET`	`/api/v1/camps/{camp_slug}/issues/{slug}`	Fetch one issue by catalog-entry slug
`GET`	`/api/v1/camps`	List camps (paginated)
`GET`	`/api/v1/camps/{slug}`	Fetch one camp by slug
`GET`	`/api/v1/sections/{section_slug}/issues`	List a section's issues (paginated)
`GET`	`/api/v1/sections/{section_slug}/issues/{slug}`	Fetch one issue by catalog-entry slug
`GET`	`/api/v1/sections`	List sections (paginated)
`GET`	`/api/v1/sections/{slug}`	Fetch one section by slug

Parameters

Parameter	Where	Description
`page`	Index endpoints	Page number, starting at 1. Out-of-range pages clamp to the last page. 25 records per page.

Pagination

Index responses carry an RFC 8288 Link header (first, prev, next, last) plus current-page, page-items, total-pages, and total-count headers. The same numbers repeat in the body's meta block:

{
  "lodges": [ ... ],
  "meta": { "page": 1, "per_page": 25, "pages": 40, "count": 991 }
}

Example

curl -H "Authorization: Bearer pv_YOUR_KEY" \
  https://patchvault.org/api/v1/lodges/netopalis/issues/netopalis-1-f1

{
  "slug": "netopalis-1-f1",
  "combined": "1 F1",
  "issue_number": "F1",
  "variety": null,
  "event": false,
  "category": "Standard Issue",
  "issue_type": { "name": "Flap", "abbreviation": "F" },
  "year": 1948,
  "date_type": "precise",
  "shape": "Flap",
  "bb6": "1 F1",
  "updated_at": "2026-05-01T12:00:00Z",
  "url": "https://patchvault.org/api/v1/lodges/netopalis/issues/netopalis-1-f1",
  "description": "...",
  "border_type": "Rolled",
  "colors": { "border": "Black", "background": "Red", "lettering": "White", "fdl": "Blue" },
  "image": { "medium": "https://...", "full": "https://..." },
  "image_back": null
}

Rate limits

Limits are per API key. The API is available to Pro accounts; exceeding the limit returns 429 Too Many Requests with a Retry-After header (seconds until the window resets).

Tier	Requests	Window
Pro	600	60 seconds

Errors

Status	Meaning
`401`	Missing, malformed, or revoked API key.
`404`	Unknown slug, or a record not publicly visible.
`429`	Rate limit exceeded — honor `Retry-After`.

Versioning & deprecation

The API is versioned in the path (/api/v1). Within a version, fields may be added at any time — clients should ignore unknown keys — but existing fields and identifiers will not change meaning or disappear. Breaking changes ship as a new path version, and a deprecated version will keep working for at least six months after its replacement is announced on the news feed.

Terms

Use of the API is subject to the site's Terms of Service. Photos are © their respective owners; personal, non-commercial use permitted.