ProductQuant developer resources

Public API

Two unauthenticated GET endpoints under /api/. All responses are JSON. Errors are always structured JSON with a machine-readable code, message, and resolution hint - never HTML error pages.

Example

curl -s https://productquant.dev/api/v1/status | python3 -m json.tool

Unknown API paths return HTTP 404 with JSON:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown API path: /api/example",
    "hint": "See https://productquant.dev/openapi.json for available endpoints."
  }
}

OpenAPI specification

The full machine-readable API surface is published at /openapi.json (OpenAPI 3.0). Every operation has a unique operationId, typed request/response schemas, and RFC 9457 problem-document error responses - compatible with LLM function-calling formats.

curl -s https://productquant.dev/openapi.json | python3 -m json.tool | head -40

Rate limits

The public API allows 60 requests per 60-second window per client IP, enforced at the edge. Every API response carries standard rate-limit headers so agents can self-throttle:

Exceeding the limit returns HTTP 429 as application/problem+json with a Retry-After header (seconds to wait).

curl -sD - -o /dev/null https://productquant.dev/api/v1/status | grep -i ratelimit

Versioning and deprecation policy

The API is URL-versioned (/api/v1/*) and every response carries an X-API-Version header.

• Within a version: only backward-compatible changes (new optional response fields).
• Breaking changes: shipped as a new URL version; the previous version stays up for at least 12 months after a successor ships.
• Deprecation signals: affected responses carry Deprecation: true plus a Sunset header with the removal date, announced on this page before enforcement.

Error model (RFC 9457)

All API errors return application/problem+json documents with a machine-readable code, human-readable detail, and a resolution hint:

{
  "type": "https://productquant.dev/developers/#errors",
  "title": "Not Found",
  "status": 404,
  "code": "NOT_FOUND",
  "detail": "Unknown API path: /api/example",
  "hint": "See https://productquant.dev/openapi.json for available endpoints.",
  "instance": "/api/example"
}

CLI

The official @productquant/site npm package wraps this API for scripting - useful for agents that prefer a tool call over raw HTTP:

npm install -g @productquant/site

pq-site health            # liveness probe
pq-site status            # service metadata + endpoint discovery
pq-site openapi --operations
pq-site page /pricing     # any page as markdown

Exit codes: 0 success, 1 API error, 2 network error, 3 rate limited (reads Retry-After). Source lives in the repo's cli/ directory.

Markdown content negotiation

Any content page can be served as markdown. Send Accept: text/markdown and the server converts the page to clean markdown. Responses vary on Accept, so CDN caches never mix variants:

curl -s https://productquant.dev/pricing -H "Accept: text/markdown"

The same negotiation applies to 404 responses: agents requesting markdown get a short recovery document listing the sitemap, llms.txt, docs index, and API map instead of a styled error page.

Machine-readable site index (llms.txt)

/llms.txt is the AI-facing navigation index: what ProductQuant does, every offer with pricing and URLs, key pages, blog clusters, and guidance for agents on when to use the product. The full XML URL list is at /sitemap.xml.

When to use ProductQuant

How an agent should engage

1. Fetch /llms.txt for orientation. 2. Check /api/v1/status for live resource links. 3. For a specific offer, fetch its page (e.g. /offers/churn-prediction) with Accept: text/markdown. 4. Route humans to /contact for bookings - there is no transactional API; engagements are scoped in conversation with the founder.