📄️ Introduction
Auth & Logging API
📄️ Platform-wide user-behavior analytics from PostHog: the Purchased→Activated→Used funnel, per-agent breakdown, and lifecycle trends (platform_admin).
Platform-wide user-behavior analytics from PostHog: the Purchased→Activated→Used funnel, per-agent breakdown, and lifecycle trends (platform_admin).
📄️ Grant an addon (quota bonus) on a metric. one_cycle = rolling only.
Grant an addon (quota bonus) on a metric. one_cycle = rolling only.
📄️ List addons (active + revoked) for a subscription.
List addons (active + revoked) for a subscription.
📄️ Paginated ledger of all quota events on a subscription. Newest first.
Paginated ledger of all quota events on a subscription. Newest first.
📄️ Read all metric usage for a subscription (platform_admin).
Read all metric usage for a subscription (platform_admin).
📄️ Revoke an addon. Idempotent (returns the revoked record).
Revoke an addon. Idempotent (returns the revoked record).
📄️ Cancel a pending tier change. Voids the open proration invoice (upgrade) or releases the SubscriptionSchedule (downgrade) and clears local pending state. The active tier is unchanged.
Cancel a pending tier change. Voids the open proration invoice (upgrade) or releases the SubscriptionSchedule (downgrade) and clears local pending state. The active tier is unchanged.
📄️ Cancel a subscription. Default is at period end (user keeps access until then); pass `immediate: true` to revoke access now and stop billing.
Cancel a subscription. Default is at period end (user keeps access until then); pass `immediate: true` to revoke access now and stop billing.
📄️ Change the plan tier on an existing subscription. Upgrades (new price > current) bill the proration immediately and only flip the tier after payment lands. Downgrades (new price ≤ current) keep the current tier until the next billing cycle.
Change the plan tier on an existing subscription. Upgrades (new price > current) bill the proration immediately and only flip the tier after payment lands. Downgrades (new price ≤ current) keep the current tier until the next billing cycle.
📄️ Deactivate (ban) a user. Bans the account, revokes active sessions, and optionally cancels active subscriptions at period end.
Deactivate (ban) a user. Bans the account, revokes active sessions, and optionally cancels active subscriptions at period end.
📄️ Generate a Stripe Checkout Session URL on behalf of the user, scoped to the given paid tier. Use for the Free→Paid upgrade path where the BE cannot bill without an authorized payment method — admin shares this link with the user; once they pay, the existing checkout-completed webhook drops them onto the new tier.
Generate a Stripe Checkout Session URL on behalf of the user, scoped to the given paid tier. Use for the Free→Paid upgrade path where the BE cannot bill without an authorized payment method — admin shares this link with the user; once they pay, the existing checkout-completed webhook drops them onto the new tier.
📄️ Full admin profile for one user — base fields, all subscriptions joined with agent + tier, and org memberships.
Full admin profile for one user — base fields, all subscriptions joined with agent + tier, and org memberships.
📄️ List platform users with a subscription summary (count + monthly spend) for the admin Users table.
List platform users with a subscription summary (count + monthly spend) for the admin Users table.
📄️ Lift the ban on a previously deactivated user.
Lift the ban on a previously deactivated user.
📄️ Change a user role. Admins cannot demote their own account; that case returns 403.
Change a user role. Admins cannot demote their own account; that case returns 403.
📄️ Register a video uploaded via /upload/presigned (platform_admin). url must be a plain S3 video file, not HLS.
Register a video uploaded via /upload/presigned (platform_admin). url must be a plain S3 video file, not HLS.
📄️ Create agent (platform_admin)
Create agent (platform_admin)
📄️ Delete an agent video (platform_admin)
Delete an agent video (platform_admin)
📄️ List agents (paginated, filterable). Slim DTO — omits longDescription, capabilities, steps, changelog.
List agents (paginated, filterable). Slim DTO — omits longDescription, capabilities, steps, changelog.
📄️ Get agent by slug (full DTO)
Get agent by slug (full DTO)
📄️ Get agent by id (full DTO)
Get agent by id (full DTO)
📄️ List videos for an agent (public)
List videos for an agent (public)
📄️ Record a 'Book a demo' intent for an agent. Fire-and-forget — appears in the admin Interactions feed and emails the configured recipients. Auth required so we can attribute the request to a user.
Record a 'Book a demo' intent for an agent. Fire-and-forget — appears in the admin Interactions feed and emails the configured recipients. Auth required so we can attribute the request to a user.
📄️ Record an 'Enterprise / Contact us' inquiry against the static Enterprise tier shown on every agent`s pricing page. Optional `message` + `companySize` are stored in interaction metadata. Auth required so the admin Interactions feed can attribute the lead.
Record an 'Enterprise / Contact us' inquiry against the static Enterprise tier shown on every agent`s pricing page. Optional `message` + `companySize` are stored in interaction metadata. Auth required so the admin Interactions feed can attribute the lead.
📄️ Soft-delete agent — sets status to inactive
Soft-delete agent — sets status to inactive
📄️ Update agent (platform_admin). capabilities/steps replace full set when present.
Update agent (platform_admin). capabilities/steps replace full set when present.
📄️ Ban a user (platform admin only)
Ban a user (platform admin only)
📄️ Create an organization
Create an organization
📄️ Request password reset email
Request password reset email
📄️ Get full organization details
Get full organization details
📄️ Get current session and user
Get current session and user
📄️ Invite a member to the organization
Invite a member to the organization
📄️ List all users (platform admin only)
List all users (platform admin only)
📄️ Current authenticated user — for frontend admin gating
Current authenticated user — for frontend admin gating
📄️ OAuth 2.1 authorization server metadata (RFC 8414)
OAuth 2.1 authorization server metadata (RFC 8414)
📄️ OIDC discovery document
OIDC discovery document
📄️ Reset password using token from email
Reset password using token from email
📄️ Set user role (platform admin only)
Set user role (platform admin only)
📄️ Sign in with email and password
Sign in with email and password
📄️ Sign out current session
Sign out current session
📄️ Sign up with email and password
Sign up with email and password
📄️ Add capability (platform_admin)
Add capability (platform_admin)
📄️ List capabilities for agent
List capabilities for agent
📄️ Delete capability (platform_admin)
Delete capability (platform_admin)
📄️ Update capability (platform_admin)
Update capability (platform_admin)
📄️ Add changelog entry (platform_admin)
Add changelog entry (platform_admin)
📄️ List changelog (newest first)
List changelog (newest first)
📄️ Delete changelog entry (platform_admin)
Delete changelog entry (platform_admin)
📄️ Health check endpoint
Health check endpoint
📄️ Idempotent install — increments installs count for the agent
Idempotent install — increments installs count for the agent
📄️ Add a notification recipient email.
Add a notification recipient email.
📄️ Remove a notification recipient.
Remove a notification recipient.
📄️ List notification recipient emails.
List notification recipient emails.
📄️ List interactions (paginated, filterable by type). Newest first; opaque cursor for next page.
List interactions (paginated, filterable by type). Newest first; opaque cursor for next page.
📄️ Edit a notification recipient email.
Edit a notification recipient email.
📄️ Create metric definition (platform_admin)
Create metric definition (platform_admin)
📄️ List metric definitions for an agent
List metric definitions for an agent
📄️ Read one metric definition
Read one metric definition
📄️ Delete metric definition (platform_admin). Fails 422 if any usage / addon / ledger row references it.
Delete metric definition (platform_admin). Fails 422 if any usage / addon / ledger row references it.
📄️ Update metric definition (platform_admin). slug and kind are immutable.
Update metric definition (platform_admin). slug and kind are immutable.
📄️ Agent telemetry — currently unavailable (501)
Agent telemetry — currently unavailable (501)
📄️ Public client metadata for consent page
Public client metadata for consent page
📄️ Rotate client_secret (platform_admin) — returns new secret ONCE
Rotate client_secret (platform_admin) — returns new secret ONCE
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ OAuth 2.1 authorization endpoint
Redirects the user to /sign-in (if not authenticated) or /consent (if first visit), then redirects back to the client `redirect_uri` with `?code=&state=`. PKCE required.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ Submit consent decision (called by the marketplace consent SPA)
POST { accept: boolean, consent_code: string }. Server redirects browser to client `redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ RP-initiated logout
Clears the marketplace session and redirects the user to `post_logout_redirect_uri`.
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Token introspection (RFC 7662)
Token introspection (RFC 7662)
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Dynamic client registration (RFC 7591) — disabled in this deployment
Currently `allowDynamicClientRegistration: false`. Returns 401. Agents are provisioned via POST /agents instead.
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ Revoke access or refresh token (RFC 7009)
Revoke access or refresh token (RFC 7009)
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OAuth 2.1 token endpoint
Exchanges authorization_code for access_token + id_token + refresh_token, or refreshes via refresh_token grant. Body must be `application/x-www-form-urlencoded`, NOT JSON.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ OIDC UserInfo endpoint
Returns claims for the user associated with the access token.
📄️ Create pricing tier (platform_admin) — auto-creates Stripe Product+Price if configured
Create pricing tier (platform_admin) — auto-creates Stripe Product+Price if configured
📄️ List pricing tiers for an agent. Public callers receive only public tiers; platform admins receive all (incl. hidden/custom).
List pricing tiers for an agent. Public callers receive only public tiers; platform admins receive all (incl. hidden/custom).
📄️ Delete pricing tier (platform_admin) — archives Stripe product if linked
Delete pricing tier (platform_admin) — archives Stripe product if linked
📄️ Toggle a tier public/hidden (platform_admin). In-place — does not touch Stripe or other fields.
Toggle a tier public/hidden (platform_admin). In-place — does not touch Stripe or other fields.
📄️ List reviews for agent (newest first)
List reviews for agent (newest first)
📄️ Delete review (author or admin)
Delete review (author or admin)
📄️ Upsert review by current user
Upsert review by current user
🗃️ schemas
76 items
📄️ Add step (platform_admin)
Add step (platform_admin)
📄️ List how-it-works steps for agent
List how-it-works steps for agent
📄️ Delete step (platform_admin)
Delete step (platform_admin)
📄️ Update step (platform_admin)
Update step (platform_admin)
📄️ Cancel at period end (free tiers cancel immediately)
Cancel at period end (free tiers cancel immediately)
📄️ Start anonymous checkout. No auth required — Stripe collects email. Returns a Stripe Checkout URL.
Start anonymous checkout. No auth required — Stripe collects email. Returns a Stripe Checkout URL.
📄️ Start checkout for a tier. Free tier creates an active sub directly. Paid tier returns a Stripe Checkout URL.
Start checkout for a tier. Free tier creates an active sub directly. Paid tier returns a Stripe Checkout URL.
📄️ Complete anonymous checkout. Called from the success page with the Stripe session ID. Finds or creates the buyer account and activates the subscription.
Complete anonymous checkout. Called from the success page with the Stripe session ID. Finds or creates the buyer account and activates the subscription.
📄️ Create a Stripe Customer Portal session. flow=overview opens the default landing; flow=cancel deep-links to the cancellation page for a specific subscription.
Create a Stripe Customer Portal session. flow=overview opens the default landing; flow=cancel deep-links to the cancellation page for a specific subscription.
📄️ Active sub for given agent (404 if none)
Active sub for given agent (404 if none)
📄️ Verify a Stripe Checkout Session post-redirect. Read-through to Stripe; never mutates DB (webhook owns writes). Use when the SPA returns from Stripe before the webhook lands.
Verify a Stripe Checkout Session post-redirect. Read-through to Stripe; never mutates DB (webhook owns writes). Use when the SPA returns from Stripe before the webhook lands.
📄️ List current user’s subscriptions
List current user’s subscriptions
📄️ Create tag (platform_admin)
Create tag (platform_admin)
📄️ List tags (paginated)
List tags (paginated)
📄️ Delete tag (platform_admin)
Delete tag (platform_admin)
📄️ List metric quotas configured on a tier
List metric quotas configured on a tier
📄️ Remove the quota row for this (tier, metric). Effective quota then falls back to 0 (deny).
Remove the quota row for this (tier, metric). Effective quota then falls back to 0 (deny).
📄️ Upsert per-metric quota on a tier (platform_admin). Pass quotaLimit=null for unlimited; 0 explicitly denies.
Upsert per-metric quota on a tier (platform_admin). Pass quotaLimit=null for unlimited; 0 explicitly denies.
📄️ Get S3 presigned PUT URL for agent image or video upload (platform_admin)
Get S3 presigned PUT URL for agent image or video upload (platform_admin)
📄️ Atomic check + increment. Idempotent on (sub, metric, clientReqId).
Agent backends call this BEFORE running the chargeable action. Returns 429 with `code: QUOTA_EXCEEDED` when the increment would breach the effective quota (base + addons). 402 when there is no active subscription. 404 when the metric slug is unknown.
📄️ List usage for every metric defined on this agent.
List usage for every metric defined on this agent.
📄️ Read usage for one metric.
Read usage for one metric.
📄️ Decrement usage for a fixed metric (e.g. site deleted). Floors at 0.
Only valid for fixed metrics. Returns 422 if called on a rolling metric.
📄️ Has the signed-in user already waitlisted for this agent? Returns `{ notified: false }` for unauthenticated callers so the FE can render the regular CTA.
Has the signed-in user already waitlisted for this agent? Returns `{ notified: false }` for unauthenticated callers so the FE can render the regular CTA.
📄️ Idempotent waitlist signup — stores email for a coming-soon agent. Duplicate (agentId, email) returns 200 silently.
Idempotent waitlist signup — stores email for a coming-soon agent. Duplicate (agentId, email) returns 200 silently.