Skip to content
weside.aiweside docs

REST API

Everything the weside app and CLI do, they do over the same HTTP API. If you want a script, a webhook handler, or your own tool to read or change companion state, you talk to that API directly.

What it is

Section titled “What it is”

A JSON REST API served by weside-core. Every route lives under a single version prefix:

https://api.weside.ai/api/v1

The surface mirrors the product: /auth, /users, /companions, /chat, /circles, /channels, /data-residency, /notes, /voice, and more (memory routes are nested under /companions/{companion_id}/memories). For the full, always-current list, fetch the OpenAPI schema at /openapi.json.

Why it matters to you

Section titled “Why it matters to you”

The MCP server and CLI cover the common cases — adopting a companion, reading memories, tracking goals. The REST API is the layer underneath: reach for it when you need something they don’t expose, or when you’re wiring weside into a system that already speaks HTTP.

How you use it

Section titled “How you use it”

Authenticate with a Bearer token — the Supabase access token from a logged-in weside session — on every request:

Terminal window
curl https://api.weside.ai/api/v1/auth/me \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

GET /api/v1/auth/me returns the current user — a quick way to confirm your token works.

List the companions on your account:

Terminal window
curl https://api.weside.ai/api/v1/companions \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

The response carries the companion IDs you then use against companion-scoped routes (chat, memory, skills). Every endpoint returns JSON; errors follow RFC 9457 problem-details, so a failure body has a machine-readable type and detail you can branch on.

Limits & edge cases

Section titled “Limits & edge cases”
  • Auth is the Supabase JWT, not a static API key. Tokens expire — refresh through the Supabase session, the same flow the app uses. (To run your companion as an LLM backend instead, see connecting your own model key.)
  • Rate limits apply per route; read endpoints and write endpoints have separate budgets. A 429 means back off.
  • Row-level security is enforced server-side. You only ever see your own data — a token can’t reach another user’s companion.
  • Treat /openapi.json as the source of truth. Routes ship continuously; this page documents the shape, not an exhaustive list.

Where next

Section titled “Where next”