Public contract · version 1.0

NaughtyPass developer resources

Build read-only catalogue tools with a small, explicit API surface. The public contract exposes site identity, category, aggregate account counts, and freshness timestamps. It never exposes credentials, user records, private notes, payment data, or administrative operations.

Read the OpenAPI spec Read agent guidance

Operation

Get public catalogue statistics

Send a GET request to /api/site-stats. A successful response contains a data array of public site records plus response metadata. The operation is deliberately read-only, accepts no parameters, and has the stable function-calling ID getPublicSiteCatalogueStats in the OpenAPI document.

curl --fail-with-body \
  --header "Accept: application/json" \
  https://naughtypass.net/api/site-stats

Errors

JSON that explains the next step

Public API failures use one envelope with a stable code, a human message, a resolution hint, and a documentation URL. Unknown /api/* paths also use this JSON shape instead of a framework HTML error page, so an agent can recover without parsing markup.

{
  "success": false,
  "error": {
    "code": "API_ROUTE_NOT_FOUND",
    "message": "The requested API route does not exist.",
    "resolution": "Use a path published in https://naughtypass.net/openapi.json.",
    "documentationUrl": "https://naughtypass.net/developers"
  }
}

Traffic policy

Self-throttle from response headers

Responses publish RateLimit-Policy and RateLimit structured fields. Treat those values as the current server hint rather than a service guarantee. If the API returns HTTP 429, stop sending requests for the number of seconds in Retry-After, then resume below the advertised rate.