API Reference

Submit API documentation by public URL, pass deterministic validation checks, and receive a structured API design review. Humans buy one review at a flat $2.00 price through embedded Stripe Checkout. Agents can either buy one flat-rate review through POST /api/mpp/review or open a usage-based streamed payment session through POST /api/mpp/review_sessions. Agent results are available through bearer auth, and human results are delivered by magic-link email when the review is ready.

How it works

1. Submit a public URL

On the homepage, provide a title, enter a public documentation URL, and add an email address. The app fetches that URL once and validates the resulting snapshot before payment.

2. Free validation first

The app runs deterministic checks before creating a charge. Suspicious or clearly non-API-looking submissions require an explicit confirmation before payment.

3. Complete Stripe Checkout

Approved submissions create a Stripe Checkout payment for $2.00. Payment confirmation happens in Checkout, but webhook fulfillment is still the source of truth for creating the purchase and starting the review.

4. Track progress and get the report by email

After Checkout completes, the success page confirms the purchase and can show the current review state once webhook fulfillment has created the review record. When the review completes, the app emails a magic link to /reports/access?token=.... Opening that link creates a session cookie for the review and redirects to /reports/:id.

Limits and access

Content limits

The app currently supports fetched source snapshots up to 500000 characters and 1500000 bytes. Larger submissions are rejected before payment.

Retention

Review source material, results, access grants, and run metadata expire on May 29, 2026 at 4:00 PM UTC. At that time, we'll purge all user data through scheduled cleanup.

Delivery model

Human access uses one-time email magic links exchanged into secure session cookies. Agent access uses bearer tokens returned after successful MPP payment, plus browser access links for human handoff when needed. Report-data access ends on May 29, 2026 at 4:00 PM UTC.

Error shape

JSON API errors use Stripe-style { error: { message, type } } responses.

{
  "error": {
    "message": "A valid email address is required",
    "type": "invalid_request_error"
  }
}

Payment

Stripe Checkout

Humans use POST /api/checkout/review to create a new $2.00 review charge. The webhook is the source of truth for fulfillment, and the embedded checkout success modal only confirms that the purchase was received.

Webhook fulfillment

POST /api/webhooks/stripe handles checkout.session.completed, finalizes the purchase, and starts the review job. If the analysis later fails, the app refunds the charge tied to the purchase.

POST/api/checkout/review

Validate submitted source material, persist a pending review, and create a Stripe Checkout session for a new review.

Request body

{
  "title": "Headless Onramp",
  "public_url": "https://docs.example.com/api/reference",
  "email": "buyer@example.com",
  "accepted_terms": true
}

Response

{
  "sessionId": "cs_test_123",
  "clientSecret": "cs_test_123_secret_456"
}

GET/api/checkout/success?session_id=cs_xxx

Confirm that the checkout session completed and report the review ID once the webhook has created the purchase row.

Request body

// No request body.
// Provide the Checkout session ID in the query string:
// /api/checkout/success?session_id=cs_test_123

Response

{
  "review_id": "rev_abc123",
  "review_status": "processing",
  "title": "Headless Onramp",
  "delivery_email": "buyer@example.com",
  "message": "Payment received. We’ll email your report when it’s ready."
}

Reviews

GET/api/reviews/:idRequires auth

Return review status and metadata for an authorized caller. Supports bearer access for agents and session-cookie access for humans.

Request body

// No request body.
// Send Authorization: Bearer tok_xxx for agent access
// or a valid browser session cookie for human access.

Response

{
  "object": "review",
  "livemode": false,
  "id": "rev_abc123",
  "title": "Headless Onramp",
  "status": "processing",
  "source_url": "https://docs.example.com/api/reference",
  "source_bytes": 52341,
  "executive_summary": null,
  "duration_ms": null,
  "created": 1711900800,
  "result_url": "https://example.com/api/reviews/rev_abc123/result"
}

Reports

Browser access

Humans should open the browser access link returned after purchase or delivered by email. That link exchanges a one-time token into a secure session cookie, then redirects to the HTML report page at /reports/:id. The browser page is intended for interactive reading rather than programmatic retrieval.

GET/reports/access?token=tok_xxx

Browser access exchange. Validates a review access token, sets a secure session cookie, and redirects to /reports/:id.

Request body

// No request body.
// Open the emailed magic-link URL directly in the browser:
// /reports/access?token=tok_xxx

Response

HTTP 307 Temporary Redirect
Set-Cookie: review_access_session=...
Location: /reports/rev_abc123

GET/reports/:idRequires auth

Render the human-readable report page in the browser. Requires a valid review access session, typically created by opening /reports/access?token=... first.

Request body

// No request body.
// Send a valid review access session cookie.

Response

<!doctype html>
<html>
  <head>...</head>
  <body>
    <main>
      <h1>Headless Onramp</h1>
      <section>Findings...</section>
    </main>
  </body>
</html>