API Reference — AI SNS CHAT

Base URL & conventions

All endpoints are served under /api on your instance host.

https://aisnsio-aisnschatwebsite.hf.space/api

Requests and responses are JSON (Content-Type: application/json), except CSV export and file-download endpoints.
Most write endpoints accept an agent selector as ?agent=<id> (query) or agentId (body). Omit it to use the workspace's first agent.
Upload endpoints under /api/sources accept up to 12 MB JSON (base64 file); all other routes cap at 1 MB.
Unknown /api/* paths return 404 {"error":"Unknown API route"}.

Authentication

Auth is a JWT (HS256, 30-day expiry) tied to your user + workspace. Obtain it by registering or logging in, then send it on every request.

The token is returned in the JSON body and set as an httpOnly cookie (aisns_token). The body token exists so the app works inside the Hugging Face iframe, where third-party cookies are blocked. Send it as Authorization: Bearer <token> — the Bearer header takes precedence over the cookie.

1. Get a token

curl -s -X POST https://aisnsio-aisnschatwebsite.hf.space/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"••••••••"}'
# → { "user": { … }, "token": "eyJhbGciOi…" }

2. Call an authenticated endpoint

TOKEN="eyJhbGciOi…"
curl -s https://aisnsio-aisnschatwebsite.hf.space/api/agents \
  -H "Authorization: Bearer $TOKEN"

3. Send a chat message

curl -s -X POST https://aisnsio-aisnschatwebsite.hf.space/api/chat \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"agentId":1,"message":"How do refunds work?"}'
# → { "reply":"…", "conversationId":42, "engine":"live+rag", "credits": 1990 }

Password changes and admin resets bump an internal token_version, which instantly invalidates all previously issued tokens for that user. Two-factor (TOTP) can be required at login (see /api/auth/2fa/*). Note: workspace "API keys" (sk_live_*) can be generated in the dashboard for your records, but the current release authenticates with the JWT above — programmatic key auth is on the roadmap.

Method	Endpoint	Auth	Body / notes
POST	`/api/auth/register`	public	`email, password (≥6), name?` → `{user, token}`
POST	`/api/auth/login`	public	`email, password, code? (2FA)` → `{user, token}`
POST	`/api/auth/logout`	public	Clears the session cookie.
GET	`/api/auth/me`	bearer/cookie	Current session: `{user, workspace, billing, impersonator}`
POST	`/api/auth/forgot`	public	`email` — always `{ok:true}` (no account enumeration).
POST	`/api/auth/reset`	public	`token, password` — logs out all sessions.
POST	`/api/auth/2fa/setup`	bearer	→ `{secret, otpauth}` (provision TOTP).
POST	`/api/auth/2fa/enable` · `/disable`	bearer	`code` — turn 2FA on/off.
GET	`/api/auth/2fa/status`	bearer	→ `{enabled}`
PATCH	`/api/auth/theme`	bearer	`theme (light\|dark)`

Errors & status codes

Errors are JSON: {"error":"message"}. Common codes:

Code	Meaning
`400`	Bad request — missing/invalid field.
`401`	Not authenticated — no/expired/invalid token.
`402`	Billing required — subscription paused or out of credits.
`403`	Forbidden — suspended account, wrong role, or admin-only.
`404`	Not found — or not owned by your workspace.
`409`	Conflict — e.g. email already registered.
`429`	Rate limited — see Retry-After.

Rate limits

Scope	Limit
Auth (register / login / forgot / reset)	20 per 5 min per IP
Public widget chat & lead capture	30 per min per IP
Authenticated chat `/api/chat`	60 per min per workspace

Agents & training

Method	Endpoint	Body / query	Description
GET	`/api/agents`	—	List workspace agents with conversation/source/lead counts.
POST	`/api/agents`	`name*, model?, system_prompt?, emoji, color, status, avatar_url, companyName, website`	Create an agent (auto public_id + agent_email + default persona).
GET	`/api/agents/:id`	—	Fetch a single agent.
PATCH	`/api/agents/:id`	`name, model, temperature, system_prompt, welcome_message, visibility, status, emoji, color, avatar_url`	Update agent fields.
DEL	`/api/agents/:id`	—	Delete an agent (cascades sources/conversations).
POST	`/api/agents/:id/test`	`message*, instructions?, model?, temperature?`	Playground test with optional unsaved overrides → `{reply, engine}`.
POST	`/api/agents/:id/train`	—	Re-index all sources; bumps `last_trained_at`.
GET	`/api/agents/:id/sources`	—	List the agent's knowledge sources.
POST	`/api/agents/:id/sources`	`type, name, content`	Add + index a source.
DEL	`/api/agents/:id/sources/:sid`	—	Remove a source.
GET	`/api/agents/default-prompt`	`company, website`	Build a default persona prompt.
GET	`/api/agents/prompt-library`	—	Ready-made persona genres.
GET	`/api/agents/company-info`	`url`	Scrape a site/social page for name, bio, logo.

All routes above require Authorization: Bearer and are scoped to your workspace.

Chat

Method	Endpoint	Body / query	Description
POST	`/api/chat`	`agentId, message*, conversationId?, stream?`; `?stream=1` for SSE	Main chat turn. Billing + credit gated (402 when out of credits). Captures leads/contacts, detects handoff, fires webhooks. Returns `{reply, conversationId, engine, credits, creditCost, captured}` or an SSE stream.

Knowledge sources

Method	Endpoint	Body / query	Description
GET	`/api/sources`	`type?, agent`	List sources (optionally filtered by type).
GET	`/api/sources/summary`	`agent`	KB size + training-status breakdown.
GET	`/api/sources/:id`	`agent`	One source with full content.
POST	`/api/sources`	`type*, name, content, url, question, answer, dataBase64, mime, sizeKb`	Add a source. Files → text-extracted (PDF/DOCX); websites → async crawl; text/Q&A → indexed.
POST	`/api/sources/social`	`url*, platform?`	Train on a public social profile's bio; borrows the avatar.
PATCH	`/api/sources/:id`	`name, content, question, answer`	Edit + re-index a source.
POST	`/api/sources/retrain`	`agent`	Re-index all of an agent's sources.
DEL	`/api/sources/:id`	`agent`	Delete + de-index a source.

Conversations & inbox

Method	Endpoint	Body / query	Description
GET	`/api/conversations`	`limit, channel, agent`	List conversations.
GET	`/api/conversations/inbox`	`agent`	Shared inbox ordered by handoff need.
GET	`/api/conversations/:cid`	—	One conversation + its messages.
POST	`/api/conversations/:cid/reply`	`text*`	Human operator reply; takes over the conversation; delivers to Slack/WhatsApp.
PATCH	`/api/conversations/:cid/handoff`	`action (takeover\|resolve\|bot)`	Change handoff state.
PATCH	`/api/conversations/:cid/messages/:mid`	`feedback (up\|down\|null)`	Thumbs on a single reply.
POST	`/api/conversations/:cid/messages/:mid/correct`	`answer*`	Save a corrected answer as a trained Q&A source.
PATCH	`/api/conversations/:cid`	`feedback`	Conversation-level thumbs.
DEL	`/api/conversations/:cid`	—	Delete one conversation.
DEL	`/api/conversations`	`agent`	Delete all conversations for an agent.
GET	`/api/conversations/channels`	`agent`	Distinct channels (filter dropdown).
GET	`/api/conversations/feedback-stats`	`agent`	Thumbs up/down rate.
GET	`/api/conversations/export.csv`	`agent`	CSV export (≤5000).

Analytics & dashboard

Method	Endpoint	Query	Description
GET	`/api/dashboard/overview`	—	Workspace KPIs + recent conversations.
GET	`/api/dashboard/usage`	—	Messages used vs tier allowance + per-agent breakdown.
GET	`/api/analytics/chats`	`agent`	Volume stats, 7-day series, top countries.
GET	`/api/analytics/topics`	`agent`	Topic buckets from first messages.
GET	`/api/analytics/sentiment`	`agent`	Positive / neutral / negative breakdown.

AI advisor (Synthia)

Synthia analyzes the whole workspace and answers questions about growing the fleet. Replies (narrative + chat) are generated in the caller's UI language — pass lang (e.g. ja, fr, ar).

Method	Endpoint	Auth	Description
GET	`/api/assistant/analysis?lang=<code>`	bearer	Fleet health score, KPIs, rule-based recommendations, and an LLM narrative written in `lang`.
POST	`/api/assistant/chat`	bearer	Chat with Synthia. Body: `{ message, history, lang, attachments[] }` — images/files as base64 data URLs (16 MB limit).

Contacts

Method	Endpoint	Body / query	Description
GET	`/api/contacts`	`search, sort, dir, limit, page, agent`	Paginated contact search.
POST	`/api/contacts`	`external_id, email, name, phone`	Create a contact.
PATCH	`/api/contacts/:cid`	`external_id, email, name, phone`	Update a contact.
DEL	`/api/contacts/:cid`	—	Delete a contact.
GET	`/api/contacts/export`	`agent`	CSV export.

Leads

Method	Endpoint	Body / query	Description
GET	`/api/leads`	`search, status, sort, dir, limit, page`	Paginated / filtered leads.
GET	`/api/leads/stats`	`agent`	Per-status pipeline counts.
POST	`/api/leads`	`name, email, phone, company, status, score, source, notes`	Create a lead.
PATCH	`/api/leads/:lid`	same fields	Update a lead.
DEL	`/api/leads/:lid`	—	Delete a lead.
GET	`/api/leads/export.csv`	`agent`	CSV export (≤5000).

Custom attributes

Method	Endpoint	Body / query	Description
GET	`/api/attributes`	`agent`	List custom contact attributes.
POST	`/api/attributes`	`name*, type, label, description`	Create an attribute.
DEL	`/api/attributes/:id`	—	Delete an attribute.

Widget & builder

Method	Endpoint	Body / query	Description
GET	`/api/widget`	`agent`	Widget config + ready-to-paste embed snippet.
PUT	`/api/widget`	`agent`; ~19 config fields	Update widget appearance/behaviour.
GET	`/api/widgets`	`agent`	List interactive builder widgets.
GET	`/api/widgets/:id`	—	One builder widget.
POST	`/api/widgets`	`name, code, schema, functions, states, mode`	Create a builder widget.
PATCH	`/api/widgets/:id`	same fields	Update a builder widget.
DEL	`/api/widgets/:id`	—	Delete a builder widget.

Channels & actions

Method	Endpoint	Body / query	Description
GET	`/api/channels`	`agent`	Deploy-channel catalog + per-agent state (secrets stripped).
POST	`/api/channels/:channel/connect`	channel creds	Connect a channel (credentials live-validated).
POST	`/api/channels/:channel/test`	—	Re-validate stored channel credentials.
PATCH	`/api/channels/:channel`	`enabled, config`	Toggle / configure / disconnect a channel.
GET	`/api/actions`	`agent`	Action catalog + enabled/config state.
POST	`/api/actions/:type/toggle`	`enabled`	Enable/disable an action.
POST	`/api/actions/:type/config`	`config, enabled?`	Save action config.

Integrations

Method	Endpoint	Body	Description
GET	`/api/integrations`	—	Connector catalog + connection state (no secrets).
POST	`/api/integrations/:provider/connect`	provider fields	Validate credentials live and store encrypted.
POST	`/api/integrations/:provider/test`	—	Re-validate stored credentials.
POST	`/api/integrations/:provider/disconnect`	—	Remove a connection.

Webhooks (outbound)

Register HTTPS endpoints to receive events. Deliveries are signed so you can verify authenticity. Only public HTTPS URLs are accepted (SSRF-guarded).

Method	Endpoint	Body / query	Description
GET	`/api/webhooks`	`agent`	List webhooks.
POST	`/api/webhooks`	`url, events[]`	Create a webhook (e.g. `leads.submit`, `message.created`, `handoff.requested`).
POST	`/api/webhooks/:id/test`	—	Send a sample event.
DEL	`/api/webhooks/:id`	—	Delete a webhook.

Custom domains

Method	Endpoint	Body / query	Description
GET	`/api/domains`	`agent`	List domains + the CNAME target to point at.
POST	`/api/domains`	`domain*`	Add a custom domain (status = checking).
POST	`/api/domains/:id/refresh`	—	Verify the CNAME via DNS lookup.
DEL	`/api/domains/:id`	—	Delete a domain.

Agent settings

Method	Endpoint	Body / query	Description
GET	`/api/settings`	`agent`	Full settings: `general, ai, voice, security, helpdesk, emails, notifications`.
PATCH	`/api/settings`	`agent`; any settings section	Update one or more settings sections.

Campaigns (outbound) Beta

Method	Endpoint	Body / query	Description
GET	`/api/campaigns`	`agent`	List campaigns + status counts.
POST	`/api/campaigns`	`name*, channel, repliesMode, templateId, audience`	Create a campaign.
POST	`/api/campaigns/:id/send`	—	Mark a campaign sent.
GET	`/api/campaigns/templates`	`agent`	List templates.
POST	`/api/campaigns/templates`	`name*, type, body`	Create a template.

Workspace & members

Method	Endpoint	Body / query	Description
GET	`/api/workspace/general`	—	Workspace record.
PATCH	`/api/workspace/general`	`name, tier`	Rename / change tier.
GET	`/api/workspace/members`	—	List members.
POST	`/api/workspace/members`	`email*, role`	Invite a member (seat-limited; emails an invite).
PATCH	`/api/workspace/members/:mid`	`role`	Change a member's role.
DEL	`/api/workspace/members/:mid`	—	Remove a member.
GET	`/api/workspace/api-keys`	—	List API keys (secret not shown).
POST	`/api/workspace/api-keys`	`name`	Create a key — full secret returned once.
DEL	`/api/workspace/api-keys/:kid`	—	Delete a key.

Billing & credits

Method	Endpoint	Auth	Description
GET	`/api/billing/pricing`	public	Public credit-bundle pricing.
GET	`/api/billing/wallet`	bearer	Current credit balance.
GET	`/api/billing/subscription`	bearer	Subscription / trial status + plans.
POST	`/api/billing/checkout`	bearer	Create a Stripe Checkout session for a bundle.
POST	`/api/billing/checkout/confirm`	bearer	Confirm a paid session (idempotent credit grant).
POST	`/api/billing/subscribe`	bearer	Start a recurring subscription (Stripe/PayPal).
POST	`/api/billing/paypal/confirm`	bearer	Confirm a PayPal subscription.
POST	`/api/billing/payment-method`	bearer	Register a payment method → start free trial.
POST	`/api/billing/auto-recharge`	bearer	Configure auto-recharge threshold + bundle.
POST	`/api/billing/cancel`	bearer	Cancel the subscription; pause the bot.

/api/billing/webhook (Stripe) and /api/billing/paypal/webhook are provider callbacks — see Inbound webhooks.

Affiliate program

Referral links, campaign tracking, KYC + payouts, and brand creatives. Affiliates earn 10% of the fees their referred workspaces pay (USD accounting), with a 60-day cookie attribution window. Mutating calls require an editor (workspace owner or member).

Method	Endpoint	Auth	Description
GET	`/api/affiliate`	bearer	Enrollment state + full dashboard (code, link, stats, tier, links, referrals, payouts, config).
POST	`/api/affiliate/enroll`	editor	Join the program. Body: `{ displayName, socials, agree:true }`.
PATCH	`/api/affiliate`	editor	Update profile: `{ displayName, socials, promoCode, notify }`.
POST	`/api/affiliate/links`	editor	Create a named campaign link. Body: `{ name, channel }`.
DEL	`/api/affiliate/links/:id`	editor	Delete a campaign link (the primary link cannot be deleted).
POST	`/api/affiliate/payout-method`	editor	Set payout method. Body: `{ method:'paypal'\|'crypto', dest, network }`.
POST	`/api/affiliate/kyc`	editor	Upload a government ID (base64 image/PDF). Sets KYC to `pending` for admin review.
POST	`/api/affiliate/payout`	editor	Request a payout. Requires admin-verified KYC + payout method; $50 minimum. Body: `{ amount }`.
GET	`/api/affiliate/leaderboard`	bearer	Top 10 affiliates by earnings + the caller's rank.
GET	`/api/affiliate/assets`	bearer	Brand kit: colors, logo URLs, and personalized creative specs with captions + hashtags.

Public referral links /r/<code> record a click, set a 60-day aff_ref cookie, and redirect to the app. KYC verification + payout processing are operator actions under Admin.

Support

Method	Endpoint	Body	Description
GET	`/api/support/tickets`	—	Your tickets + categories.
POST	`/api/support/tickets`	`subject, message, category, priority`	Open a ticket.
GET	`/api/support/tickets/:id`	—	Ticket + thread (owner or admin).
POST	`/api/support/tickets/:id/messages`	`body*`	Reply on a ticket.

Public widget API no auth

These power the embeddable widget and are keyed by an agent's public id — no Bearer token. CORS-open, rate-limited per IP.

Method	Endpoint	Body / query	Description
GET	`/api/public/:publicId`	—	Non-secret widget config (name, welcome, colors, suggestions).
POST	`/api/public/:publicId/chat`	`message (≤4000), conversationId?`	Anonymous chat vs a public agent. Billing/credit gated; captures leads; handoff detection.
POST	`/api/public/:publicId/lead`	`name, email, phone, note`	Capture a lead from the widget form.
GET	`/api/public/:publicId/poll`	`conversationId, after`	Poll for new operator messages since `after`.
GET	`/api/config`	—	Non-secret platform UI config.
GET	`/api/content/:page`	—	Landing-page CMS content.
GET	`/api/health`	—	Liveness + DB check.

Inbound webhooks signature-verified

These receive events from third parties. They verify a provider signature over the raw request body — do not send them yourself.

Method	Endpoint	Verification	Description
POST	`/api/slack/events`	Slack HMAC (5-min replay guard)	Slack Events API — DM/@mention → reply posted back.
GET	`/api/whatsapp/webhook`	verify_token	Meta subscription handshake.
POST	`/api/whatsapp/webhook`	Meta HMAC (`x-hub-signature-256`)	Inbound WhatsApp messages → reply via graph/relay.
POST	`/api/billing/webhook`	Stripe HMAC (`stripe-signature`)	Stripe subscription / payment events.
POST	`/api/billing/paypal/webhook`	PayPal verification API	PayPal subscription events.

Admin operator only

The entire /api/admin/* surface and /api/backups/* require an admin account (requireAdmin). These are for the platform operator (株式会社フリーボーン), not tenant integrations — listed here for completeness.

Area	Endpoints
Revenue & stats	`GET /api/admin/revenue`, `/stats`, `/activity`, `/llm-diagnostics`
Users	`GET/PATCH/DELETE /api/admin/users/:id`, `/password`, `/credits`, `/role`, `/subscription`, `/edit-session`, `/impersonate`
Workspaces & agents	`GET /api/admin/workspaces`, `/agents`; `PATCH/DELETE /api/admin/agents/:id`
Content (CMS)	`GET/PUT /api/admin/content`, `POST /content/reset`
Platform settings & bundles	`GET/PUT /api/admin/settings`, `/bundles`
Tickets	`GET /api/admin/tickets`, `PATCH /tickets/:id`
Affiliates	`GET /api/admin/affiliates`, `GET /affiliates/:id/kyc-doc`, `POST /affiliates/:id/kyc`, `GET /affiliate-payouts`, `POST /affiliate-payouts/:id`
Backups	`GET /api/admin/backup`; `GET/POST /api/backups`, `GET /api/backups/download/:name`