stern-api/API_RECONSTRUCTION.md

Stern Insider API reconstruction

Reason for existence: provides a reproducible, OpenAPI-compatible inventory of the public API surface at https://iop-dev.strndev.com/ without publishing opaque webhook secrets.

Deliverables

File	Purpose
openapi.reconstructed.json	Valid OpenAPI 3.0.3 manifest; 257 URLconf paths and 249 observed operations.
endpoint-options-evidence.json	Sanitized, read-only OPTIONS evidence for each path.
endpoint-get-evidence.json	Sanitized GET status/content-type/byte-count and inferred JSON shapes; no response values.
endpoint-validation-evidence.json	Sanitized models from intentionally invalid credential/registration validation requests.
django-404-urlpatterns.routes.txt	Sanitized path inventory parsed from Django's public DEBUG 404 page.
reconstruct_openapi.py	Re-runs the read-only discovery process.

Evidence and confidence

The manifest was generated from Django's public DEBUG 404 URLconf, then OPTIONS was issued with Accept: application/json for every discovered API/webhook route. Public GET routes were fetched to model response fields across all returned array items. Six credential/registration validation routes were sent {}; their observed JSON validation models are included without storing response values. This exposed methods, authentication challenges, five request serializers, 20 public GET response shapes, and six validation-error response models.

Item	Result
Discovered API/webhook paths	257
Observed methods	123 GET, 122 POST, 1 PATCH, 3 DELETE
OPTIONS returned 200	51
Auth-gated OPTIONS (401/403)	187
Public GET response shapes inferred	20
Request-body serializers exposed	5
Operations with concrete request examples	5
Operations with concrete response examples	26
URLconf paths with no inferable method	8

The request schemas directly exposed by Django REST Framework are present for:

• POST /api/v2/token/ — username, password
• POST /api/v2/token/refresh/ and /api/v3/token/refresh/ — refresh, access
• POST /api/v4/auth/login/ — request_metadata, email, password, remember_me
• POST /api/v4/auth/register/ — first_name, last_name, username, initials, email_consent, background_color_id, avatar_id, location_info, age_restricted

Authentication

The manifest defines bearerAuth as JWT bearer authentication. Server evidence includes WWW-Authenticate: Bearer realm="api" on protected v4 endpoints. The URLconf also exposes legacy/session authentication and token routes, including /api-token-auth/, /api/v2/token/, /api/v2/token/refresh/, and logout endpoints. No account was created: registration or login is unnecessary for this read-only reconstruction.

Important limitations

• This is a reconstruction, not an official contract. A 401/403 response can hide serializer metadata and response schemas.
• GET schemas are sampled from one public response only; optionality, enum domains, pagination, and item variation are not guaranteed.
• Eight URLconf paths are retained with x-reconstruction-status but have no operation because OPTIONS supplied no Allow header (parameterized detail/download routes, SSO, specific webhooks, and several server-error routes).
• Opaque webhook tokens exposed by DEBUG are replaced with {webhook_secret}. Do not recover or commit those tokens.
• Re-running the script causes one deliberate 404, OPTIONS, public GET requests, and six deliberately invalid POST validation requests. It performs no login, registration, successful POST, PATCH, or DELETE.

HTML routes excluded from the manifest

These are server-rendered/admin/tooling routes rather than the JSON API explorer surface: /, /admin/, /dashboard/, /auth/, /accounts/, /tools/, /business_registration_invitation/, /index, /login/, /pro/, /machine_registration/, /game_alerts/, /game_audits/, /game_play/, /clear_game_play/, /generate_emails/, /resend_confirmation_email/, /generate_notifications/, /tools/create_user/, /password-change/, /password-change/done/, /favicon.ico, /api-auth/, and /tz_detect/.

Two opaque-named diagnostic HTML routes are intentionally not reproduced. healthz/ is also excluded because it is an operational health endpoint, not a Django API explorer endpoint.

Verify

cd /Users/jordan/Downloads/stern-api
python3 reconstruct_openapi.py
npx --yes @apidevtools/swagger-cli@latest validate openapi.reconstructed.json