API & tooling reference

The whole public support surface. POST opens a conversation for an (app, end_user_ref) pair or appends to the open one; GET polls for new messages. CORS-open, no cookies, no SDK required.

Auth: Public ingest key (`app_key`) + the caller's own `end_user_ref`

curl -X POST https://soleos.app/api/support/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "app_key": "pk_...",
    "end_user_ref": "hy2Nq8Rf3vKp1sLd7wZx4tCb",
    "message": "The game crashes on level 3",
    "client_message_id": "aX9...",
    "metadata": { "app_version": "1.4.2", "os_version": "Android 15",
                  "device_model": "SM-A155F", "locale": "tr-TR" }
  }'

# → 201 {"conversation_id":"...","message_id":42,"status":"open","duplicate":false}
#   200 with "duplicate":true when this client_message_id already landed

curl "https://soleos.app/api/support/v1/messages?app_key=pk_...&end_user_ref=hy2N...&since=42"
# → {"status":"open","messages":[...],"cursor":43,"poll_after_ms":15000,"app":{...}}

end_user_ref is a bearer secret: 16-200 chars of [A-Za-z0-9._:-], stored only as SHA-256. Send it as X-End-User-Ref where your client can set headers. Rate limited per ref, per IP and per app; ETag + since make a steady-state poll cost no rows and no body.

The v0 widget protocol (actions open/send/poll), kept as a translation layer over the v1 core so script tags already embedded on live sites keep working.

Auth: Public ingest key (`app_key`) + the caller's own `end_user_ref`

curl -X POST https://soleos.app/api/widget \
  -H 'Content-Type: application/json' \
  -d '{"action":"open","key":"pk_...","meta":{"page":"/pricing","lang":"en"}}'
# → {"token":"...","greeting":"...","accent":"#F2A93B","messages":[]}

Frozen on purpose. `token` here IS a v1 `end_user_ref` — same value, same hash — so a browser holding one keeps its thread across the migration. New integrations should use v1.

The v0 embeddable chat widget, served as dependency-free JS in a Shadow DOM.

Auth: None — public

<script src="https://soleos.app/widget.js" data-soleos="pk_..."></script>

The same widget speaking v1, with a persisted outbox that retries rather than dropping messages.

Auth: None — public

<script src="https://soleos.app/widget/v1.js" data-soleos="pk_..."></script>

Migrating from /widget.js is a one-line src change: this script adopts the old script's stored token so returning visitors keep their history.

SoleOS's own in-dashboard feedback box — a signed-in SoleOS user messaging the founder. Stores to `soleos_feedback` and pings admins by email and Telegram.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Not the customer support inbox. End users of your products come in through /api/support/v1/messages.

Inbox bootstrap: conversations, apps, canned replies, projects and settings in one request. PATCH updates the workspace's support settings (notification thresholds, agent locale, default reply mode).

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

One conversation. GET returns the full history and marks it read. POST takes an `action`: reply, status, read, translate, preview, draft, approve_draft, discard_draft, relabel_language.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

curl -X POST https://soleos.app/api/support/agent/thread \
  -H 'Content-Type: application/json' \
  -d '{"conversationId":"...","action":"reply","body":"On it.","translate":true}'

`translate: true` sends in the user's language and stores both texts — body is what went over the wire, body_en is what you typed.

Register a product for support, mint or rotate its public ingest key, revoke it, and set its reply mode (human / auto_ack / ai_draft / ai_auto).

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Canned replies: list, create, edit, delete. Ordered by real use.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Tickets, filed per project from a conversation. POST with `auto: true` asks Claude to summarise the thread in English; without it, pass your own title and body.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Keys are per project and assigned by a database trigger under an advisory lock, e.g. PUFFZE-7.

Unread badge count for the sidebar. One indexed count, no joins.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Mint or rotate a project's webhook secret and hand back the ready-to-paste Supabase trigger SQL or Firebase function snippet.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

The secret is shown once and stored as a SHA-256 hash.

Viral Loop lifecycle webhook: `post.published` and `run.failed`.

Auth: Provider signature / shared secret header

X-ViralLoop-Signature: <hmac>   # verified against VIRAL_LOOP_WEBHOOK_SECRET

Refuses everything with 503 when the secret is unset rather than degrading into trusting unsigned input.

Resend bounce and complaint webhook. Hard bounces and spam complaints are auto-suppressed so a dead list cannot poison the sending domain shared by every product.

Auth: Provider signature / shared secret header

Svix-Id / Svix-Timestamp / Svix-Signature   # verified against RESEND_WEBHOOK_SECRET

Stripe → Supabase sync, keeping each workspace's plan and subscription status current so the paywall can trust the database.

Auth: Provider signature / shared secret header

Stripe-Signature: <sig>   # verified against STRIPE_WEBHOOK_SECRET

Telegram bot webhook. Handles /start <code> (links a chat to a workspace) and /stop.

Auth: Provider signature / shared secret header

X-Telegram-Bot-Api-Secret-Token: <secret>   # set when the webhook was registered

Newsletter capture. Writes through the service role because the table has no anon policy. Rate limited per IP.

Auth: None — public

One-click unsubscribe (RFC 8058). Deliberately unauthenticated — an opt-out that first asks you to sign in is not an opt-out.

Auth: None — public

GET  /api/unsubscribe?token=<signed>   # human-facing confirmation page
POST /api/unsubscribe                  # List-Unsubscribe-Post from the mail client

The token is HMAC-signed and scoped to one address and mail kind.

This reference, as one plaintext file — every endpoint, its auth and runnable examples in a single fetch. What an AI agent should be pointed at instead of crawling /docs.

Auth: None — public

curl https://soleos.app/docs.md

Rendered from the same lib/api-catalog.ts as the web page, so the two cannot say different things.

Product summary for AI assistants, generated from content/product-facts.json at build time so it cannot drift.

Auth: None — public

RSS 2.0 for the blog and answers series, so readers, aggregators and AI crawlers get every post the moment the engine publishes it.

Auth: None — public

PKCE code exchange — the landing point for magic links.

Auth: Signed state / cookie from the matching `start` leg

Create a project. Enriches it with the site's declared theme colour, favicon, or an exact-name App Store artwork match — misses stay null rather than being invented.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Update a project (name, platforms, website, status) or delete it.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Re-pull one project's connected sources on demand instead of waiting for the daily cron.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Public-share settings for one project. Writes mint an unguessable share token.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Audit the project's website for SEO and AI-answer readiness.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Top content posts for one project — which hook actually earned the reach.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Every connection in the workspace with its provider, health and last pull. Drives the sidebar Sources widget.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Remove a project's connection(s) for a provider. Snapshots already captured are left in place.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

AI insights: GET the latest stored brief, POST to generate one, PATCH to mark an item done, DELETE to clear.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Requires ANTHROPIC_API_KEY and is dormant without it. Respects the per-workspace AI opt-out.

Goals CRUD. The arrival-date maths lives in lib/goals.ts and runs client-side against the same series the chart draws.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

PUT provisions a project's widget key (used by the project page). GET and POST answer 410 — they moved to /api/support/agent/*.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Stripe Connect OAuth, leg 1. Read-only; state is HMAC-signed.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Stripe Connect OAuth, leg 2. Verifies state, swaps the code, attaches the account.

Auth: Signed state / cookie from the matching `start` leg

RevenueCat OAuth, leg 1: send the user to RevenueCat's approval screen with read-only scopes. State is HMAC-signed so the callback can trust which workspace it belongs to.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

RevenueCat OAuth, leg 2. Stashes the token bundle in Vault.

Auth: Signed state / cookie from the matching `start` leg

PostHog OAuth, leg 1. PKCE S256 public client (CIMD — the client_id is a URL we host).

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

PostHog OAuth, leg 2: verify the PKCE verifier, exchange the code, and store the grant before redirecting back with an immediate first pull.

Auth: Signed state / cookie from the matching `start` leg

Google Analytics 4 OAuth, leg 1. offline + consent so a refresh token is issued.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

GA4 OAuth, leg 2: verify the cookie, exchange the code, stash the token in Vault on the project's ga4 connection, then return the user to pick a property.

Auth: Signed state / cookie from the matching `start` leg

Search Console OAuth, leg 1: Google consent for read-only Search Console, with offline + consent so a refresh token is issued.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Search Console OAuth, leg 2: verify the cookie, exchange the code, stash the token in Vault, then return the user to pick a verified site.

Auth: Signed state / cookie from the matching `start` leg

Supabase Management OAuth, leg 1. PKCE plus a signed context cookie.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Supabase OAuth, leg 2: verify the signed context cookie, exchange the code for a management token, and stash it in Vault on the project's supabase connection.

Auth: Signed state / cookie from the matching `start` leg

Workspace-level RevenueCat import from a v2 secret key; the key goes to Vault.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List the RevenueCat projects the connected grant can see, so the user picks which one maps to this SoleOS project.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Link a chosen RevenueCat project to a SoleOS project.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Per-project RevenueCat link using whichever account grant applies.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Validate a PostHog personal API key (query:read) and attach a traffic connection.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List GA4 properties the account can read, flattened across accounts.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Record which GA4 property this project tracks. The puller reads config.propertyId from here on every run.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List the verified Search Console sites the account owns, so the user picks which property maps to this project.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Record which verified Search Console site this project tracks. The puller reads it from the connection config on every run.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List Supabase projects the connected account can see.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Install the signup trigger through the Management API — no copy-paste.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

App Store Connect via a pasted API key (issuer id, key id, .p8).

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Google Play Console. Install counts come from the Play-managed GCS bucket.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Firebase, connected by pasting a service-account key — no manual Cloud Function to deploy. The key goes to Vault.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Bing Webmaster Tools, connected by pasting an API key. Adds search impressions and clicks for Bing-family engines.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List Viral Loop apps the workspace key can see, auto-matched to SoleOS projects.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Confirm the whole Viral Loop match set at once — the match is portfolio-wide.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Create or reuse the workspace's Stripe customer and open a Checkout Session with a 7-day trial. Returns a URL to redirect to.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Open the Stripe billing portal. Returns a URL to redirect to.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Current workspace plan and subscription status.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

List the team, invite by email, change a role, revoke. Every mutation is owner-only and re-checks the caller's role server-side.

Auth: Signed-in session — workspace owner only

Workspace-level notification preferences — currently whether integration health changes are worth telling you about.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

The per-workspace AI opt-out promised on /ai. Turning it off makes every AI feature dormant rather than degraded.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Telegram link management: GET status, POST mints a one-time code and t.me deep link, DELETE unlinks.

Auth: Signed-in session (Supabase auth cookie), workspace-scoped

Platform admin: list and approve waitlisted workspaces. Defaults to the owner; override with SOLEOS_ADMIN_EMAILS.

Auth: Signed-in session — platform admin only

The metric pullers. One route, one puller per provider, with per-connection error isolation so a failing connection is marked and the run continues.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

curl -X POST https://soleos.app/api/pull -H "Authorization: Bearer $PULL_SECRET"

Cron: daily 06:00 UTC.

Weekly portfolio digest email: MRR and week delta, top movers, nearest milestone ETAs, signal counts.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: Mondays 08:00 UTC.

Re-check connections that could not validate at connect time (e.g. a Play grant that had not propagated).

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: every 6 hours.

Submit every public URL to IndexNow so Bing-family engines pick up new pages in minutes.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: daily 07:30 UTC.

Answers-engine cron: at most one grounded post per run.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: 06:50 and 17:50 UTC.

Weekly Site Health sweep, so the score becomes a tracked series rather than a one-off number.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: Mondays 05:20 UTC.

The support notification batching tick. Sends nothing most runs; the threshold logic lives in lib/support/notify.ts.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Cron: every 5 minutes.

Walk-forward backtest of the projection engine against every project's real MRR history.

Auth: `Authorization: Bearer $PULL_SECRET` (or `$CRON_SECRET`)

Run manually.

Signal ingest gateway

A Supabase Edge Function, not a Next.js route. One endpoint receives every lifecycle signal — signups from your own backend, purchases and churn from RevenueCat — and turns them into events, notifications and emails.

Auth: `Authorization: Bearer $SOLEOS_INGEST_SECRET`, or the per-project webhook secret minted by /api/connections/webhook

curl -X POST "$SUPABASE_URL/functions/v1/ingest?source=app&project=puff-zero" \
  -H "Authorization: Bearer $SOLEOS_INGEST_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"type":"signup","payload":{"desc":"new user"}}'

Idempotent by construction: dedupe_key is the source plus the provider's event id (or a body hash), and a unique index makes a provider's retries no-ops. Source lives at supabase/functions/ingest/index.ts.