# Ahya

> Ahya is a self-hostable, agent-first knowledge base for collaborative documents, REST APIs, and remote MCP clients.

Ahya combines a real-time collaborative Markdown editor, a versioned REST API, and a remote Model Context Protocol (MCP) server backed by one shared permission model.

## Public discovery & documentation

- [Ahya home](https://ahya.wild.as/): Collaborative workspace entry and installation overview
- [Interactive REST API reference](https://ahya.wild.as/api/docs): Local Swagger UI and API overview (supports `Accept: text/markdown`)
- [OpenAPI 3.1 specification](https://ahya.wild.as/openapi.json): Canonical REST contract (also at `https://ahya.wild.as/api/openapi.json`)
- [RFC 9727 API catalog](https://ahya.wild.as/.well-known/api-catalog): Machine-readable API linkset
- [XML sitemap](https://ahya.wild.as/sitemap.xml): Public indexable endpoints

## Remote MCP server

- [Streamable HTTP MCP endpoint](https://ahya.wild.as/mcp): Requires OAuth 2.1 (PKCE + RFC 8707 `resource`) or a workspace-bound Bearer PAT
- [AI Catalog](https://ahya.wild.as/.well-known/ai-catalog.json): Domain-level discovery pointing to the server card
- [MCP Server Card](https://ahya.wild.as/mcp/server-card): Canonical server card (also at `https://ahya.wild.as/.well-known/mcp/server-card.json`)
- [MCP Registry manifest](https://ahya.wild.as/server.json): Registry-compatible server metadata

## Authentication & scoped permissions

- **OAuth 2.1 discovery**: `https://ahya.wild.as/.well-known/oauth-protected-resource/mcp`, `https://ahya.wild.as/.well-known/oauth-protected-resource/api/v1`, and `https://ahya.wild.as/.well-known/oauth-authorization-server/api/auth` (root alias at `https://ahya.wild.as/.well-known/oauth-authorization-server`).
- **Scopes**: `docs:read` (read spaces, documents, graph, versions, search), `docs:write` (create, patch, comment), `admin` (manage ACLs, workspace members, invitations, domains), and `offline_access` (refresh tokens).
- **Personal Access Tokens**: Workspace-bound `Authorization: Bearer <PAT>` credentials created by signed-in members.

## Versioning, rate limits & error format

- Versioned REST routes live under `https://ahya.wild.as/api/v1`.
- Rate limits are 1,200 requests/minute per transport peer and 240 requests/minute per authenticated user across REST and MCP, reported via `RateLimit-Policy`, `RateLimit`, and `Retry-After` on HTTP 429.
- API errors return JSON with `{ "error": { "code", "message", "hint?", "details?" } }`.
