Owlish Docs

Developer overview

What's programmable in Owlish — REST API, MCP server, authentication, and where to find the full reference.

These docs are the user guide for the Owlish console. If you’re integrating Owlish into a larger system — automating source updates, embedding the agent in a custom flow, or connecting it to your own tooling — this page is your starting point. The full API reference lives at api.owlish.bot/docs.

What’s programmable today

The current API surface focuses on knowledge-base management — useful for keeping the agent’s content in sync with another system of record (a CMS, a docs repo, a help-center exporter). Per the API key scopes, the available operations are:

  • Sources Read — list and inspect knowledge sources.
  • Sources Write — create and update sources.
  • Sources Delete — remove sources.

More of the agent surface (agents, channels, sessions, skills) is on the roadmap; track changes in the changelog under your console avatar.

Authentication

API access is via API keys, created and scoped under Settings → API keys. Each key has a name, a set of scopes, and a prefix shown in the keys list (the full key is shown only once at creation — copy it into your secrets manager immediately).

Authorization: Bearer sk_live_…

For the request/response shape of each endpoint, see api.owlish.bot/docs.

MCP server

Owlish also exposes itself as a Model Context Protocol server, so MCP-aware clients (Claude Desktop, Claude Code, Cursor, and other MCP hosts) can call into your workspace without bespoke integration code. Connect by pointing your MCP client at the Owlish MCP endpoint with an API key as the auth token.

The MCP server exposes the same scoped operations as the REST API — Sources Read/Write/Delete today, more as the surface grows.

Webhooks

Webhooks for session events (handoff requested, session resolved, etc.) are on the roadmap. Until then, the recommended pattern is polling the sessions endpoints from your integration on a schedule that fits your latency budget.

Best practices

  • One key per integration. Don’t share a single key across multiple systems — you lose attribution and can’t revoke without breaking everything.
  • Smallest scopes that work. Don’t grant Sources Delete to an integration that only needs to read.
  • Rotate keys periodically. The “Last used” timestamp on the keys list helps spot stale keys.
  • Never commit keys to source control. Use environment variables or a secrets manager.

Next steps