Developer documentation

Build on the Wisent App platform.

Canonical contracts for iOS, Android, the web application, backend services, private media, data migrations, and signed messaging integrations.

Client surfaces

iOS

Native Swift application with local-first chat and character workflows.
App Store release metadata and TestFlight automation are release inputs, not runtime configuration.
Room and persona state is owned by the authenticated account and synchronized through the application API.

Android

Native Android client using the same authenticated application contracts.
The package is com.wisent.android and is distributed through Google Play.
Platform UI may differ; conversation, persona, document, and media ownership rules do not.

Service APIs

Application API

The web and mobile clients authenticate before calling the stateless application API. That service owns business logic and database access, while generation is delegated to a separately deployed authenticated inference service.

Method	Path	Contract
POST	/api/chat	Run an authenticated conversation turn.
GET · POST	/api/conversations	List or create conversations.
GET	/api/conversations/search	Search the caller’s conversations.
GET · DELETE	/api/conversations/{id}	Read or remove one owned conversation.
GET · POST · DELETE	/api/personas	Manage caller-owned personas.
POST · GET	/api/documents	Upload or list caller-owned documents.
POST	/webhooks/user-inactivity	Receive the authenticated inactivity event.
GET	/health · /api/health	Report application-service health without coupling it to inference readiness.

Inference and platform bridges

Inference, training, and App Store automation deploy independently from the application API. The inference service owns tokenization and generation; training consumes queued offline work; the App Store bridge verifies webhooks and emits normalized GitHub dispatches.

Method	Path	Contract
POST	/v1/generate	Generate text as a blocking response or server-sent event stream.
GET	/health	Report inference readiness as ready, warming, or unhealthy.
POST	/webhooks/app-store-connect	Verify an App Store Connect webhook and dispatch its stable identifiers.
GET	/health	Report App Store webhook bridge process health.

Off-platform messaging

Authenticated users can link an existing character and conversation to WhatsApp, Telegram, or iMessage. Linking returns a platform deep link; callers must treat delivery status separately from link creation.

Method	Path	Contract
POST	/api/messaging/whatsapp/connect	Link a phone number and character to WhatsApp.
POST	/api/messaging/telegram/connect	Issue a single-use Telegram deep-link token.
POST	/api/messaging/imessage/connect	Link a phone number and character to iMessage.
GET	/api/messaging/status	Read the caller’s per-platform link state.

Private image service

Generated image objects remain private under stado://wisent-images. The application returns only short-lived HMAC-signed proxy URLs; clients never receive object-store credentials.

Method	Path	Contract
POST	/image-generate/	Create an image-generation job.
GET	/image-generate/images/{uuid}.{ext}	Read an authorized image through the signed proxy.
GET	/image-generate/health	Report image pipeline readiness.
GET	/health	Report process health.

Local MLX backend

Apple Silicon deployments provide local model inference, JWT authentication, control-vector training, and multi-armed-bandit notification scheduling without silently falling back to a remote provider.

Method	Path	Contract
POST	/api/chat	Run local model inference.
GET · POST	/api/control_vectors	List or train control vectors.
GET	/api/job/{id}	Read the durable state of a training job.
GET · POST	/api/mab/notifications/{schedule\|statistics\|pending\|history}	Operate and inspect the notification bandit.

Data and migrations

Canonical schema

wisent-supabase-wisent-app migrations are the schema source for project rbqjqnouluslojmmnuqi.
Pull-request CI checks migrations; the default branch is the deployment boundary.
Application code must not treat dashboard edits or local snapshots as canonical schema.

Optimization service

Supported steering comparisons include CAA, DAC, BiPO, REFT, and RepEng.
Requests identify steering type and layer configuration explicitly.
Optimization results are versioned artifacts; clients do not infer compatibility from filenames.

Tour messaging bridge

The FastAPI bridge exposes GET /health and signed POST /webhook. A webhook is admitted only for x-webhook-event: message.received, a timestamp no more than five minutes old, and an HMAC-SHA256 signature over <timestamp>.<raw body>.

Resolve the sender through Supabase imessage_users; unlinked senders receive account-link guidance.
Detect explicit travel or location intent.
Call POST /api/messaging/tour-chat with { messages, user_id, location? } and x-agent-secret.
Reply through Ultrareach POST /v3/chats/{chat_id}/messages with the service bearer.

Required secrets: SERVICE_API_TOKEN, AGENT_TOOL_SECRET, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, and TOUR_BRIDGE_SIGNING_SECRET(S). Optional bases default to local Ultrareach on port 8080 and https://app.wisent.ai.