Skip to content
Faultline

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.

User API Key (BYOK)

Bring your own LLM provider key. Scans are routed directly to your provider — no Faultline subscription required. Billing is between you and your provider.

  1. 1Obtain an API key from your LLM provider (Google AI Studio, OpenAI Platform, or Anthropic Console).
  2. 2Pass it as the x-user-api-key header on POST /api/scan requests.
  3. 3The key must be at least 20 characters. It is never logged or stored server-side.
  4. 4Billing checks and scan limits are bypassed — your provider's rate limits apply instead.

Endpoints

Scanning

Submit text for claim extraction and verification via SSE streaming. Accepts Clerk session auth (subscribed users) or x-user-api-key (BYOK — no subscription required).

Upload multiple files for batch claim scanning.

Create a shareable link for a completed scan result.

Update an existing shared scan with new data or status.

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 text with failed claims.

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.