Owlish exposes a focused developer surface for keeping an agent’s knowledge in sync with another system of record. Start with the machine-readable Owlish OpenAPI specification or browse the interactive Owlish API reference.
Predictable developer resources
| Resource | URL |
|---|---|
| OpenAPI 3.1 JSON | owlish.bot/openapi.json |
| RFC 9727 API catalog | owlish.bot/.well-known/api-catalog |
| Interactive API reference | api.owlish.bot/docs |
| OAuth protected-resource metadata | api.owlish.bot/.well-known/oauth-protected-resource/mcp |
| MCP Streamable HTTP endpoint | https://api.owlish.bot/mcp |
| MCP Registry-compatible manifest | owlish.bot/mcp/server.json |
| Agent onboarding skill | owlish.bot/agent-onboarding/SKILL.md |
| Machine-readable onboarding facts | owlish.bot/agent-onboarding.json |
All discovery files and documentation are public. Workspace data endpoints and MCP tools require authorization.
REST API
The current API manages knowledge folders and sources. It can create folders, list and inspect sources, upload base64-encoded files, crawl webpages, update metadata, retry failures, run syncs, restore recycled sources, and delete content.
Base URL: https://api.owlish.bot/v1
curl -s https://api.owlish.bot/v1/folders \
-H "Authorization: Bearer $OWLISH_API_KEY"Fetch the OpenAPI document before constructing a request. Every operation has a
unique operationId, a description, typed input and output schemas, and an
x-required-scopes declaration suitable for function-calling adapters.
Authentication and least-privilege scopes
REST API access uses a workspace API key created under
Settings → API keys. Keys begin with owl_wsk_,
are shown once, and are accepted as Bearer tokens:
Authorization: Bearer owl_wsk_…Choose the smallest set of scopes the integration needs:
knowledge_base:read— list and inspect sources and folders.knowledge_base:write— create, update, sync, retry, and restore sources and folders.knowledge_base:delete— soft-delete or permanently delete sources and folders.
The same catalog is machine-readable in the OpenAPI security scheme and the
RFC 9728 scopes_supported field. API and MCP access are available on Growth
and Scale workspaces; Free remains a no-card way to evaluate the Owlish product,
but it is not an API sandbox.
MCP server
The Owlish MCP server uses the standard Streamable HTTP transport at
https://api.owlish.bot/mcp. MCP clients can use OAuth 2.1 discovery, or pass an
Owlish API key as a Bearer token. OAuth authorization advertises the same three
scopes, and the server only registers tools allowed by the granted scopes.
Use the server manifest for registry-style discovery and the protected-resource metadata for OAuth discovery.
An official local CLI proxy exists in the Owlish source tree, but the
@owlish/mcp npm package is not public yet. Use the hosted endpoint until a
public npm registry link appears here.
Rate limits and environment boundaries
The REST API allows 100 requests per minute per API key and returns standard rate-limit headers. There is no separate public sandbox today: API calls operate on the workspace attached to the credential. Use a dedicated test workspace and a narrowly scoped key when validating an integration.
What is not programmable yet
Programmatic agent creation, billing changes, channel installation, and session webhooks are not part of the public API. Complete those tasks in Owlish Console. Do not infer endpoints that are absent from the OpenAPI document.
Next steps
- OpenAPI JSON — generate clients or function definitions.
- API keys — create, scope, rotate, and revoke credentials.
- Agent onboarding skill — split human and automatable onboarding steps.
- Help & support — request an endpoint or report an integration issue.