Route Boundaries

Woes exposes several route families with different callers, credentials, and data visibility. Keep those boundaries intact when you build integrations, install the widget, or extend the platform.

Route Families

Family	Who calls it	Credential	Data boundary
Public REST API	Your server-side integrations.	Workspace API key such as `woesk_...`.	Workspace-scoped resources intended for external automation.
Widget routes	Customer browsers with a widget install.	Widget public key, plus conversation secret for conversation-bound reads and writes.	Only the visitor’s widget conversation, public widget configuration, and customer-facing surfaces.
Public docs routes	Anyone with the published docs URL.	Public slug.	Sanitized generated docs for ready published sources.
Verified widget identity	Your backend, then the customer’s browser.	Server-held widget identity secret creates a short-lived proof. The browser sends the proof to `/api/widget/identity`.	Attaches name, email, and external ID to the current widget visitor without exposing the secret.
Client portal routes	Authenticated customer portal users.	Portal session.	Customer-visible portal issues and membership records for that portal account.
Account routes	Authenticated Woes operators and admins.	Woes user session.	Workspace settings, inbox data, clients, issues, docs ingestion, automations, billing, and operator workflows.
Team Chat routes	Authenticated Woes operators.	Woes user session.	Internal workspace chat channels, direct messages, reactions, attachments, and presence.
Webhooks	External providers such as Stripe, Discord, and GitHub.	Provider-specific signature or installation verification.	Provider event payloads mapped to the connected workspace or installation.
Admin routes	Platform operators only.	Admin session and platform authorization.	Cross-workspace operational data.

Public REST API

Use /api/v1/* routes from trusted server-side code only. These routes authenticate with workspace API keys and are documented in the API Reference. Do not call the public REST API directly from a browser, mobile app, widget script, or static docs site. REST API keys can read or mutate workspace data and must not be exposed to customers.

Public Docs Routes

Published source docs are available under /docs/{slug}. These routes are public read-only documentation surfaces for ready sources. They do not accept workspace API keys, widget keys, source auth credentials, or operator sessions, and they should never expose source secrets, private metadata, or operator debug data. Widget routes are browser-safe only because they are constrained by the widget public key, route-level validation, rate limits, and conversation secrets. A widget public key identifies which workspace and agent the widget belongs to. It is not an account credential. Common widget routes include:

Route	Purpose
`GET /api/widget/config`	Load public widget configuration.
`POST /api/widget/identity`	Attach a verified visitor identity from a server-generated proof.
`POST /api/widget/messages`	Send visitor messages.
`GET /api/widget/messages`	Read messages for the current conversation.
`POST /api/widget/presence`	Record visitor presence.
`POST /api/widget/events`	Record widget lifecycle events.
`GET /api/widget/feedback`	Load enabled customer-facing survey prompts.
`POST /api/widget/csat`	Submit CSAT or NPS feedback.
`GET /api/widget/updates`	Load unread client updates for the current visitor.
`POST /api/widget/updates/read`	Mark client updates as read.

See Widget Routes for request shapes and security notes.

Identity Boundary

Verified widget identity always starts on your backend. Your app should authenticate the user, create the Woes identity proof using the server-held widget identity secret, and return only the public identity payload plus proof to the browser. The browser should then call Woes('identify', ...) or your installed wrapper after the widget loader is ready. It is safe to retry identity on mount, focus, and auth state changes. Woes treats repeated identity calls as an upsert for the same visitor. Never place the widget identity secret, REST API keys, source auth secrets, or service-role credentials in frontend code, Mintlify pages, GitHub repos, mobile apps, or screenshots.

Account And Team Chat Routes

Authenticated workspace routes require a Woes operator session. These routes power the Woes app, including clients, issues, notes, live chat, email, Discord, API source ingestion, automations, surveys, updates, account settings, and Team Chat. Team Chat routes are internal collaboration routes. They are not customer messaging channels and should not be called from customer widgets, public sites, or third-party integrations. Use the Woes UI for Team Chat unless you are extending the app itself. See Team Chat and Route Map for the active route families.

Webhooks

Webhook routes must verify provider signatures or installation metadata before they mutate workspace data. Treat webhook payloads as untrusted until they pass provider-specific validation and workspace mapping. Examples include Stripe billing events, Discord interactions, GitHub installation callbacks, and inbound email provider events.

Rules

Never use REST API keys in the browser.
Never treat a widget public key as an account credential.
Keep widget identity secrets on your backend only.
Keep API source credentials separate from documentation content.
Scope every workspace-owned record by workspace or a tenant-owned parent.
Do not expose operator-only debug data to customers.
Prefer documented public APIs over internal account routes for external integrations.

See the complete Route Map.

Woes documentation

Route Boundaries

Route Boundaries

Route Families

Public REST API

Public Docs Routes

Widget And Customer Routes

Identity Boundary

Account And Team Chat Routes

Webhooks

Rules

​Route Boundaries

​Route Families

​Public REST API

​Public Docs Routes

​Widget And Customer Routes

​Identity Boundary

​Account And Team Chat Routes

​Webhooks

​Rules

Route Boundaries

Route Families

Public REST API

Public Docs Routes

Widget And Customer Routes

Identity Boundary

Account And Team Chat Routes

Webhooks

Rules