Owndom API

Access

API keys are issued by Owndom's administrator. Member accounts use Owndom through the web app and the phone and Windows apps. For API access, write to [email protected].

Address and versions

Base address: https://owndom.alk.homes/agent-api/v1/
Every answer under /v1 carries the header x-owndom-api-version: 1.
Changes to v1 add fields or routes; anything that has to change in a way that would break a script is announced on What's new first.

Keys and scopes

Send the key in the Authorization header:

curl https://owndom.alk.homes/agent-api/v1/auth/whoami \
  -H "Authorization: Bearer hk_…"

A key acts as the account it belongs to: it sees that account's chats and files and nothing else.
A key is shown once, stored only as a hash, and can be revoked at any time; anything using it stops at once.
Scopes limit a key further. Give a script the narrowest scope it needs:

Scope	What the key may do
`read`	Read only (`GET` requests).
`chat`	Talk to agents: start chats, send messages and follow the live reply. Includes `read`.
`write`	Make changes the account is allowed to make, such as files, designs, tasks and memories. Includes `chat` and `read`.

A key with no scopes can do everything its account can.

Requests and answers

JSON in, JSON out (Content-Type: application/json). File downloads and the live reply stream are the exceptions.
An agent's reply arrives as a stream of server-sent events.
When a free model is out of quota, the reply says so, and Owndom switches to another free model where it can.

Errors

Errors are JSON with an error field (a few gateway errors use detail):

Status	Meaning
400	Invalid request; `detail` says what is wrong.
401	No key, or the key isn't valid.
403	Not allowed. A scoped key gets `insufficient_scope` with the scope it needs; an account that isn't confirmed or approved yet gets `email_unverified` or `pending_approval`.
404	Not found, or not yours.
409	Already running (for example, a chat that is still replying).
413	Request too large.
429	Too many requests: wait and try again.

Python package

The owndom Python package wraps the API: chats with agents (including the live reply), files, memories and the rest, plus ToolServer for giving agents your own tools over MCP. It needs Python 3.9 or newer and nothing else. Signed in, download the newest version from https://owndom.alk.homes/agent-api/sdk/python/download and install it with pip install owndom-*.whl. Like every API call, it needs an API key.

Routes

Generated from the access rules the server enforces: 78 route patterns as of 2026-10-31. "Anyone" routes need no sign-in (health checks, sign-in itself, payment webhooks); "signed in" routes need a key or a session and only ever reach that account's own data. Routes not listed here are for the administrator only. A key's scope must cover the call: read for looking, the scope in the right-hand column for changes.

Service

Route	Methods	Who	Key scope (read / change)
`/`	GET, HEAD	anyone	`-` / `admin`
`/health`	GET, HEAD	anyone	`-` / `admin`
`/healthz`	GET, HEAD	anyone	`-` / `admin`
`/version`	GET, HEAD	anyone	`-` / `admin`

Accounts & keys

Route	Methods	Who	Key scope (read / change)
`/auth/invite/:code`	GET, HEAD	anyone	`-` / `admin`
`/auth/signup`	POST	anyone	`admin` / `-`
`/auth/sse-token`	GET, HEAD	signed in	`read` / `admin`
`/auth/verify`	GET, HEAD	anyone	`-` / `admin`
`/auth/verify/resend`	POST	anyone	`admin` / `-`
`/auth/whoami`	GET, HEAD	anyone	`-` / `admin`

Sign-in (Better Auth)

Route	Methods	Who	Key scope (read / change)
`/api/auth/**`	*	anyone	`-` / `-`

Your account

Route	Methods	Who	Key scope (read / change)
`/account/age`	GET, HEAD, POST	signed in	`read` / `write`
`/account/billing/checkout`	POST	signed in	`admin` / `write`
`/account/billing/portal`	POST	signed in	`admin` / `write`
`/account/consent`	GET, HEAD, POST	signed in	`read` / `write`
`/account/delete`	POST	signed in	`admin` / `write`
`/account/export`	GET	signed in	`read` / `admin`
`/account/export/files`	GET	signed in	`read` / `admin`
`/account/model-keys`	*	signed in	`read` / `write`
`/account/model-keys/:provider`	*	signed in	`read` / `write`
`/account/model-limits`	GET, HEAD	signed in	`read` / `admin`
`/account/model-prefs`	PUT	signed in	`admin` / `write`
`/account/plan`	GET, HEAD	signed in	`read` / `admin`
`/account/plan-survey`	POST	signed in	`admin` / `write`
`/account/training-choice`	POST	signed in	`admin` / `write`
`/account/training-optout`	POST	signed in	`admin` / `write`

Chat & agent runs

Route	Methods	Who	Key scope (read / change)
`/sessions`	*	signed in	`read` / `chat`
`/sessions/**`	*	signed in	`read` / `chat`

Agents

Route	Methods	Who	Key scope (read / change)
`/agents`	GET, HEAD	signed in	`read` / `admin`
`/agents/:name`	GET, HEAD, PUT, DELETE	signed in	`read` / `write`
`/agents/:name/duplicate`	POST	signed in	`admin` / `write`
`/agents/:name/preview`	GET, HEAD	signed in	`read` / `admin`

Tasks, goals & missions

Route	Methods	Who	Key scope (read / change)
`/goals`	GET, HEAD, POST	signed in	`read` / `write`
`/goals/:id`	*	signed in	`read` / `write`
`/goals/:id/**`	*	signed in	`read` / `write`
`/symphony/missions`	GET, HEAD, POST	signed in	`read` / `write`
`/symphony/missions/:id`	*	signed in	`read` / `write`
`/symphony/missions/:id/**`	*	signed in	`read` / `write`
`/tasks`	GET, HEAD, POST	signed in	`read` / `write`
`/tasks/:id`	*	signed in	`read` / `write`
`/tasks/:id/**`	*	signed in	`read` / `write`
`/tasks/plans/:plan_id/approve`	POST	signed in	`admin` / `write`
`/tasks/plans/:plan_id/reject`	POST	signed in	`admin` / `write`

Tools, skills & commands

Route	Methods	Who	Key scope (read / change)
`/commands`	GET, HEAD	signed in	`read` / `admin`
`/commands/:name/render`	POST	signed in	`admin` / `write`
`/rules`	GET, HEAD, PUT	signed in	`read` / `write`
`/skills`	GET, HEAD	signed in	`read` / `admin`
`/skills/:name/render`	POST	signed in	`admin` / `write`
`/tools`	GET, HEAD	signed in	`read` / `admin`

Files & code

Route	Methods	Who	Key scope (read / change)
`/files/**`	*	signed in	`read` / `write`
`/snapshots`	*	signed in	`read` / `write`
`/snapshots/**`	*	signed in	`read` / `write`

Memory & knowledge

Route	Methods	Who	Key scope (read / change)
`/memories`	*	signed in	`read` / `write`
`/memories/:id`	*	signed in	`read` / `write`

Models & settings

Route	Methods	Who	Key scope (read / change)
`/permissions/:id`	POST	signed in	`admin` / `write`
`/providers/catalog`	GET, HEAD	signed in	`read` / `admin`
`/providers/privacy`	*	signed in	`read` / `write`
`/settings`	GET, HEAD	signed in	`read` / `admin`

Studios

Route	Methods	Who	Key scope (read / change)
`/design`	*	signed in	`read` / `write`
`/design/**`	*	signed in	`read` / `write`
`/image`	*	signed in	`read` / `write`
`/image/**`	*	signed in	`read` / `write`

People

Route	Methods	Who	Key scope (read / change)
`/people/**`	*	signed in	`read` / `write`

Messages & notifications

Route	Methods	Who	Key scope (read / change)
`/mailbox`	*	signed in	`read` / `write`
`/mailbox/**`	*	signed in	`read` / `chat`
`/push`	*	signed in	`read` / `write`
`/push/**`	*	signed in	`read` / `write`
`/spaces/summarize`	POST	signed in	`admin` / `chat`

Devices & phones

Route	Methods	Who	Key scope (read / change)
`/devices`	*	signed in	`read` / `write`
`/devices/**`	*	signed in	`read` / `write`
`/devices/report`	POST	anyone	`read` / `-`

Quality, data & cost

Route	Methods	Who	Key scope (read / change)
`/activity`	GET, HEAD	signed in	`read` / `admin`
`/activity-log`	GET, HEAD	signed in	`read` / `admin`
`/activity-log/stats`	GET, HEAD	signed in	`read` / `admin`

Integrations, plugins & SDK

Route	Methods	Who	Key scope (read / change)
`/sdk/python`	GET	signed in	`read` / `admin`
`/sdk/python/download`	GET	signed in	`read` / `admin`

Billing

Route	Methods	Who	Key scope (read / change)
`/billing/webhook`	POST	anyone	`admin` / `-`
`/billing/webhook/:provider`	POST	anyone	`admin` / `-`

Privacy

Requests made with a key follow the same rules as the app: a chat on a cloud model is sent to the provider you choose, and data is kept as described in the Privacy policy.

Questions

Write to [email protected].

The Owndom API