Smohix Technologies HQ · programmable surface

Developer platform

Build secure integrations with Smohix

Use the same-origin HTTP API, API keys, and documented ingest paths to connect operational workflows — without inventing endpoints or exposing private backends in the browser.

Docs hub →Request builder →Status →Security →

Products = ecosystem · Platform = operating core · Developers = programmable surface. API keys live at Settings → API keys after sign-in (secret shown once).

Request core

What you can build today

Capabilities below map to routes and settings that already exist in this repository.

Request lifecycle

From access to observability

Access
Enter the developer surface
Open API docs, then sign in to mint keys or ingest tokens.
Authenticate
Choose the correct credential
Session cookies, smohix_sk_ keys, ingest tokens, and provider signatures are not interchangeable.
Request
Call a documented route
Use the catalog — only routes implemented under app/api are claimed.
Route
Match auth to the handler
API keys authenticate reasoning/robot proxies — not every console session route.
Response
Handle status and bodies
Expect 401/403 for auth, 429 when limited, and JSON error fields where implemented.
Observe
Status, limits, and audit
Public status, documented rate limits, and console audit for operational evidence.

Authentication architecture

Authentication

Credentials are purpose-scoped. Do not treat session cookies, API keys, ingest tokens, and provider signatures as interchangeable.

Human session
Supabase Auth cookies
Console and most product API routes use browser sessions after sign-in.
Programmatic access
smohix_sk_ API keys
Bearer or X-Smohix-Api-Key for /api/reasoning/* and /api/robot/* only.
Ingest / machine access
smohix_ingest_ and smohix_ca_
Alert/vuln ingest tokens and compliance assessor tokens — separate from API keys.
Signed provider events
Webhook signatures
PayPal, Lemon Squeezy, and Slack verify signatures — never expose signing secrets in clients.

Browser sessions: Supabase Auth cookies on console and most product API routes.
API keys: Authorization: Bearer smohix_sk_… or header X-Smohix-Api-Key for /api/reasoning/* and /api/robot/*.
Alert ingest: dedicated Bearer ingest tokens (smohix_ingest_…) per workspace.
Assessor access: smohix_ca_ tokens for compliance assessor routes.
Provider webhooks: signature verification (PayPal, Lemon Squeezy, Slack) — never expose signing secrets in clients.
Legacy key prefixes remain accepted for compatibility where implemented (see API key token helpers).

Endpoint architecture

Featured routes

Representative routes from the live catalog. Full list lives in the HTTP API reference.

GET/api/healthPublic
Liveness and uptime for load balancers.
POST/api/integrations/alertsIngest token
Alert ingest opens or deduplicates incidents.
GET|POST/api/reasoning/*Session or smohix_sk_
Reasoning connector proxy — API-key eligible.
GET|POST/api/robot/*Session or smohix_sk_
Robot connector proxy — API-key eligible.

Full endpoint catalog →

SDK architecture

SDK & CLI status

Only statuses below are claimed. Preview and planned items are not published packages.

TypeScript / Next.js (this repo)
Open-source web app at github.com/aicodeai50/SMOHIX — primary integration surface today.
Available
Smohix SDK (@smohix/sdk)
Preferred TypeScript package name for the Smohix API client. Publishing is in progress — use the documented REST catalog and API keys until the package is released.
Preview
Python SDK
Planned — use the Smohix HTTP API and API keys until published.
Coming soon
CLI
Planned developer CLI for keys, ingest testing, and health checks.
Planned

HQ routes are served under /api/… without a public /v1 path segment today. Treat the catalog as the source of truth; a full versioned public API may be introduced later without inventing endpoints here.

Webhook architecture

Inbound boundaries

Inbound ingest
Alert and vulnerability ingest with Bearer ingest tokens (optional HMAC).
Billing / provider callbacks
Signature-verified billing webhooks where configured.
Slack approvals
Approval callbacks for guarded operational workflows.
General outbound subscriptions
Not available — there is no general developer “subscribe to events” webhook API.

Webhook documentation → · Integrations →

Security · status · limits

Secure integration

Store API keys server-side only (environment variables or a secret manager).
Prefer least privilege: one key per integration so you can revoke without downtime elsewhere.
Rotate keys after personnel changes or suspected exposure; revoke first, then replace.
Call Smohix over HTTPS only (production: https://smohix.run).
Never embed API keys in front-end bundles, mobile apps, or public repositories.

Rate limits: Sensitive routes enforce in-memory limits (Upstash when configured). Proxy routes typically allow 120 requests per 60 seconds per user+IP. Alert and vulnerability ingest apply similar per-IP limits. Responses may include retry_after / Retry-After when limited.

Security →Trust →Status →API keys docs →

Quick start

Six steps to a supported request

1. Sign in
Create a workspace session so you can mint keys and configure ingest.
2. Create an API key
Settings → API keys. The full secret is shown once — copy it immediately.
3. Store the key securely
Use an environment variable or secret manager. Never commit keys to Git.
4. Make a supported request
Call /api/health (public) or authenticate /api/reasoning/* and /api/robot/* with Bearer smohix_sk_…
5. Handle errors
Expect 401/403 for auth, 429 when rate limited, and 5xx for upstream or server failures.
6. Rotate or revoke keys
Revoke compromised keys in Settings immediately, then mint a replacement.

First authenticated request

Example uses a clearly fake key prefix. Replace with a secret from Settings → API keys. API keys authenticate the reasoning and robot proxies — not every console route.

HTTP example · server-side only

// Server-side only — never expose smohix_sk_ keys in browsers
const key = process.env.SMOHIX_API_KEY; // e.g. smohix_sk_example_not_a_real_secret
if (!key) throw new Error("Missing SMOHIX_API_KEY");

const res = await fetch("https://smohix.run/api/reasoning/health", {
  headers: {
    Authorization: `Bearer ${key}`,
    // or: "X-Smohix-Api-Key": key,
  },
});
if (!res.ok) {
  const body = await res.text();
  throw new Error(`HTTP ${res.status}: ${body}`);
}
const data = await res.json();
console.log(data);

Errors & rate limits

401 — missing or invalid session / API key / ingest token.
403 — org role or plan does not allow the action.
404 — resource not found (route-dependent).
429 — rate limit exceeded (sensitive routes apply IP or user+IP limits).
5xx — server or upstream connector failure (for example 502 when a proxy backend is unreachable).

Smohix AI (separate product)

Smohix AI lives at https://ai.smohix.run and is not the same surface as this HQ HTTP catalog. Console Copilot uses same-origin /api/copilot/chat with server-side configuration — HQ API keys authenticate reasoning/robot proxies here, not the Smohix AI product site.

Open Smohix AI ↗

API request builder

Copy example requests for documented routes — run them in your terminal or server. Requests are not executed from this page.

Open full request builder →

API request builder — generates copyable examples only. Requests are not executed from this page. Use your own terminal or server with a valid API key.

Public liveness — no authentication.

Example request (not executed)

curl -s https://smohix.run/api/health

Example response shape

{
  "ok": true,
  "service": "smohix-web",
  "uptime_s": 12345
}

Usage and billing

Plan and checkout behavior are documented on /pricing. Developer APIs here do not introduce self-serve payment flows. Configure billing only through existing signed-in settings when available.

Pricing →Docs hub →Changelog →

Build secure integrations with Smohix

What you can build today

From access to observability

Authentication

Supabase Auth cookies

smohix_sk_ API keys

smohix_ingest_ and smohix_ca_

Webhook signatures