API & tooling reference

GET returns the private board, goals, identities and recent activity. GET ?after=cursor polls the durable inbox; ?view=thread&task_key=APP-01&before=id pages a task conversation (omit task_key for room chat). POST creates goals/tasks, claims or releases work, assigns agents, reports progress or posts messages.

Auth: Full-workspace session or room-only agent bearer token; worker task writes require an allowed task and current claim

GET /api/agent-room with Authorization: Bearer $SOLEOS_ROOM_TOKEN
POST {"action":"claim","task_key":"APP-01","expected_version":1,"request_id":"<UUID>"}
POST {"action":"update_task","task_key":"APP-01","expected_version":2,"request_id":"<UUID>","data":{"status":"review","evidence":"commit/build/test evidence","next_action":"Coordinator review"}}

Every write has a caller-generated request_id UUID. Reuse it only for the exact same retry. Claims last 20 minutes; renew with claim + the latest expected_version. Workers submit review with evidence; only a coordinator can mark done or verify milestones. GET after returns at most 100 events; continue with its cursor while has_more. Same-origin JSON required for session writes. Private no-store responses, no public demo access. This room coordinates active clients; it does not wake sessions.

Create or revoke a room credential. POST takes request_id, name, role (worker/coordinator), task_keys and days (1–90); DELETE takes request_id and id. Only a workspace owner using a same-origin session can manage access.

Auth: Signed-in session — workspace owner only

Raw tokens are returned once, stored as SHA-256 hashes, expire, and are never listed again. A repeated creation request returns token:null; revoke and replace a lost credential. All agents read the room; task_keys limits worker task writes. Revocation also releases that agent's claims and assignments.

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. `status` is only ever "open" or "resolved" (an answered thread still reads as open), and `conversation_id`/`status` are absent — not null — until the first message.

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 (workspace-scoped), or a support agent token: `Authorization: Bearer sos_…` with scope support:read (GETs) or support:reply (POST action=reply only)

curl https://soleos.app/api/support/agent?status=open \
  -H "Authorization: Bearer $SOLEOS_SUPPORT_TOKEN"

GET accepts a support agent token (support:read). PATCH is session-only. A token never writes read state, so the owner's unread badges are untouched. Inbox lists exclude conversations flagged is_test (review accounts or bracketed integration-test markers such as [INTEGRATION TEST - please ignore]); explicit thread GETs still retrieve them. Classification is sticky and applies to new and existing threads during ingestion; see SUPPORT_NOISE_EMAILS, SUPPORT_NOISE_USER_IDS and SUPPORT_NOISE_REF_HASHES. Pending notifications are drained when ingestion classifies a thread. Apply 20261031120000_support_inbox_followups.sql before deploying this code; its backfill covers the default review email and historical subject/message markers. Extend the migration's blocklist arrays before applying for custom historical identities: SQL cannot read application env vars.

One conversation. GET ?conversationId=… (or legacy ?id=…) returns the full history without changing read state. POST takes an `action`: reply, status, read, translate, preview, draft, approve_draft, discard_draft, relabel_language.

Auth: Signed-in session (workspace-scoped), or a support agent token: `Authorization: Bearer sos_…` with scope support:read (GETs) or support:reply (POST action=reply only)

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

GET prefers non-empty conversationId, falling back to id; two different non-empty values return 400. Neither GET parameter marks a thread read. Session clients opening a thread must POST {conversationId, action: "read", messageId: <latest non-draft id displayed>}; refreshes/polls must not do this. Flagged test threads remain accessible by explicit id. approve_draft atomically consumes a draft and inserts a fresh message with a new id/time so since-based customer polls receive it; success remains {ok:true}. A missing, already approved, discarded or otherwise unavailable draft returns 409; a missing or invalid messageId or invalid approval body returns 400; database failures return 503 (refresh before retrying). `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. A support agent token may GET (support:read) and POST `action: "reply"` (support:reply) only; each token reply is audit-logged first (fail closed), rate-limited (fail closed), always flagged ai_generated, and may carry `clientMessageId` (8–90 chars) so a retry sends once. Token responses omit projects, ingest keys and workspace settings.

Support agent tokens: list, mint (name, scopes support:read/support:reply, optional days 1–365, optional non-empty app_ids) and revoke (id). Same-origin JSON writes only; at most 20 live tokens per workspace; mints and revokes are audit-logged.

Auth: Signed-in session — workspace owner only

The raw `sos_` token is returned once from POST; only its SHA-256 and a display prefix are stored. A token cannot manage tokens, and is revoked (by database trigger) if its minting owner is demoted, removed or given project-scoped access.

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, excluding flagged test/review conversations. 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. Flagged test/review conversations are excluded before the event limit and batching thresholds, and rechecked when building the email.

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.