API reference

The Wholisphere API is REST + JSON. The full machine-readable spec lives at:

https://api.wholisphere.ai/openapi.json

Render it with Scalar, Stoplight Elements, Swagger UI, or your IDE’s OpenAPI plugin.

Routes

Method	Path	Auth	Purpose
GET	/v1/health	none	Liveness + LLM config probe
POST	/v1/auth/request	none	Send magic-link sign-in email
GET	/v1/auth/callback	token (query)	Verify token, set session cookie
GET	/v1/auth/me	session cookie	Current user + memberships
POST	/v1/auth/logout	session cookie	Clear session
GET	/v1/orgs/:orgId/keys	session	List API keys
POST	/v1/orgs/:orgId/keys	session (admin)	Create new API key
POST	/v1/orgs/:orgId/keys/:keyId/revoke	session (admin)	Revoke key
GET	/v1/orgs/:orgId/audit	session	Recent audit events
POST	/v1/billing/checkout	session (admin)	Stripe Checkout session
POST	/v1/billing/portal	session (admin)	Stripe Customer Portal
POST	/v1/webhooks/stripe	Stripe signature	Subscription lifecycle webhook
POST	/v1/intent	api-key	Page intent extraction
POST	/v1/describe	api-key	Image description
POST	/v1/explain	api-key	Text simplification
POST	/v1/summarize	api-key	Page summarization
POST	/v1/voice-action	api-key	Voice → action plan
POST	/v1/telemetry	api-key	Opt-in usage events
POST	/v1/vpat	api-key	Generate VPAT markdown
POST	/v1/cache/invalidate	api-key	CI/CD cache refresh

Conventions

• All requests use application/json content type.
• All responses carry an x-trace-id header — paste it into support tickets.
• All errors are JSON envelopes: { "error": { "code": "...", "message": "...", "traceId": "...", "retryable": true|false } }.
• Versioning: every route is under /v1/. Breaking changes ship under /v2/ with /v1/ maintained for at least 12 months.

Rate limits

Free tier: 30 req/min, 1,000 req/day per org. Pro tier: 300 req/min, 30,000 req/day. Platform tier: custom (typically 3,000 req/min, unlimited daily).

429 responses include a Retry-After header.

SDKs

Coming soon:

• @wholisphere/sdk (TS/JS) — covers all routes with typed responses
• wholisphere-python (Python) — for analyzer integration

In the meantime any HTTP client works.