Skip to content
FaultlineAlpha

API Documentation

Authentication

Clerk Session Token

Authenticate via Clerk session cookies. Ideal for browser-based integrations where the user is already signed in.

  1. 1Sign in via the Faultline web app or Clerk-hosted sign-in page.
  2. 2The session cookie is automatically attached to requests from the same origin.
  3. 3For cross-origin requests, pass the session token in the Authorization header as a Bearer token.

Widget API Key (Embed)

Server-generated keys scoped to the embeddable scan widget. Keys are issued out-of-band (contact support or use the admin console). A self-service management UI is on the roadmap.

  1. 1Request a widget key from support — keys are provisioned manually today.
  2. 2Include the key in the x-api-key header when calling POST /api/scan from the widget.
  3. 3Scans made with a widget key bypass Clerk session auth and are rate-limited per key.

Organization Context

Access workspace resources by including organization context. Requires Clerk + Org auth.

  1. 1Ensure your Clerk session has an active organization selected.
  2. 2The organization ID is read from Clerk auth context automatically.
  3. 3Workspace endpoints require the user to be a member of the organization.

Endpoints

Scanning

Submit text for claim extraction and verification via SSE streaming. Accepts Clerk session auth, a widget key in the x-api-key header, or an anonymous request carrying a Cloudflare Turnstile token in x-turnstile-token (1 free scan per IP every 30 days).

Upload multiple files for batch claim scanning.

Create a shareable link for a finished scan. A share carries only the text and the claims Faultline found, never a verdict: viewers run their own scan to verify. Send the text and the `complete` result's `claims`, `signature` and `signedAt` unchanged. Only a claim list this server signed for you and that exact text, under 7 days old, is accepted; anything else is refused with 400 `unverified_result`. 503 `share_unavailable` when sharing is not configured.

Revoke a shared scan you own. A shared report cannot be edited: any field other than `id` and `revoke: true` is refused with 400 `immutable_field`.

Get the current status and data for a shared scan.

History

List the authenticated user's scan history entries.

Save a new scan result to the user's history.

Clear all scan history for the authenticated user.

Delete a single history entry by ID.

Analysis

Generate a critique and counter-prompt for a completed scan. Requires the critiqueToken field of the final `complete` event streamed by POST /api/scan, sent as the x-critique-token request header together with result.claims and result.verifications from that same event and the scanned text, unchanged. The token is bound to that exact text, claims and verifications, expires after 10 minutes, and is single-use: missing → 401 critique_token_required; invalid, expired, reused, or sent with different text, claims or verifications → 403 critique_token_invalid. Only claims, verifications and text are forwarded.

Analyze the weakest links across claims and verification results.

Billing

Create a Stripe checkout session for subscription upgrade.

Get the current subscription status for the authenticated user.

Stripe webhook endpoint for subscription lifecycle events. Validates stripe-signature header.

Notifications

List notifications for the authenticated user.

Mark all notifications as read.

Workspace

List scan history for the active workspace organization.

Save a scan result to the workspace history.

Clear all workspace scan history.

Delete a single workspace history entry by ID.

Admin

List all users with their subscription and usage data.

Upload a CSV file to bulk-invite users via Clerk. Returns a job ID for polling progress.

Poll the status of a bulk import job.

List audit log entries. Supports action and search query parameters.

Frameworks

List frameworks. Use scope=marketplace (public), scope=own (org), or scope=available (org + marketplace).

Create a new custom compliance framework.

Get a single framework by ID.

Update a custom framework. Only name, description, iconName, relevantRuleIds, sections, and isPublic may be changed.

Delete a custom framework by ID.