Docs · Alexandria

01 — humans

Quickstart for humans

From empty account to a searchable library in a few minutes.

01
Create an account
Sign up at /signup with Google or email. Then sign in at /login.
02
Create a workspace
Onboarding at /onboarding creates your first workspace. You can switch workspaces later from the app header.
03
Add your first source
Open /app/sources/new. Paste content, point at a URL, or register a pointer. Pick a tier (managed / indexed / pointer) and type.
04
Search the library
Use /app/search or the dashboard quick search. Hits cite their source so you can open the original.
05
Invite teammates
Admins invite members from /app/settings. Billing and plan limits live under /app/settings/billing.

02 — agents

Quickstart for agents & API

Same registry your team browses — reachable over HTTPS and MCP with an API key.

1. Create an API key

In /app/settings, create a key. Keys look like alx_…. Send them as Authorization: Bearer alx_…. The key is scoped to its workspace.

2. Base URL

https://api.alexandria.page

3. Curl examples

Hybrid search (vector + keyword). Optional return_mode: raw (default), headroom, or llm_extract (needs a query for extract).

curl -s https://api.alexandria.page/v1/search \
  -H "Authorization: Bearer alx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pricing model",
    "top_k": 5,
    "return_mode": "headroom"
  }'

List sources:

curl -s "https://api.alexandria.page/v1/sources" \
  -H "Authorization: Bearer alx_YOUR_KEY"

Add a managed note-like source (content or url required for managed/indexed):

curl -s https://api.alexandria.page/v1/sources \
  -H "Authorization: Bearer alx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 strategy notes",
    "source_type": "note",
    "tier": "managed",
    "content": "We are focusing on enterprise seats…",
    "tags": ["strategy"]
  }'

Read the wiki index:

curl -s https://api.alexandria.page/v1/wiki/index \
  -H "Authorization: Bearer alx_YOUR_KEY"

4. MCP setup

Endpoint: https://api.alexandria.page/mcp. Authenticate with the same Bearer API key. Example Cursor MCP config:

{
  "mcpServers": {
    "alexandria": {
      "url": "https://api.alexandria.page/mcp",
      "headers": {
        "Authorization": "Bearer alx_YOUR_KEY"
      }
    }
  }
}

Tools include search_context, search, search_code, recent_prs, fetch_source, add_source, write_note, read_wiki_page, search_wiki, list_skills, fetch_skill.

MCP exposes these individual primitives; it does not currently expose the web app's Ask pipeline as one tool. The calling agent plans its own search sequence.

03 — integrations

Integrations & asynchronous indexing

Creating a connector stores configuration and secret references. It does not deploy a worker, start Slack, run GitHub sync, or create a schedule.

Slack · Socket Mode

Alexandria listens for Events API message events over a Socket Mode WebSocket; it is not a public webhook receiver. The Slack app needs an xapp-… token with connections:write, an installed xoxb-… bot token, bot events message.channels and message.groups, and bot scopes channels:read, groups:read, channels:history, and groups:history. Invite the bot to private channels it must read and reinstall after changing scopes.

Add tokens under Settings → Connectors, choose channel IDs for the allowlist, and have an operator deploy the persistent Slack worker. Empty allowlist means channels the bot can already receive and read; it does not grant Slack access. New activity refetches and indexes the complete affected thread. There is no bulk history backfill: an operator may sync one known thread at a time, and attached file contents are not downloaded.

GitHub · scheduled/poll sync

Alexandria does not receive GitHub webhooks. Add a dedicated, least-privilege PAT and repository config under Settings → Connectors. The token needs read access to repository metadata, contents/commits, and pull requests. Each repo entry has owner, name, and an optional default_branch; connector-level path_allow and path_deny arrays filter paths, with deny winning.

An operator must deploy the GitHub worker, call its private /sync endpoint for the first run, and schedule later calls. Initial sync is capped at 200 eligible files per repository. Later runs use commit comparisons for changed, non-removed files; removed paths are not archived today. recent_prs separately reads live open PRs, newest-updated first, from GitHub repos that pass Alexandria's ACL mapping.

When does content become searchable?

Source creation and connector ingestion are asynchronous. The evidence worker consumes document-ready, the embeddings worker consumes evidence-ready, and the wiki worker consumes source-ingested. All three workers and their Pub/Sub subscriptions must be healthy. A source write returns before those stages finish; callers can poll GET /v1/sources/:id/processing.

See the interactive system flow for the complete connector, queue, worker, Search, Ask, and ACL paths.

04 — retrieval

Query broadly, then follow citations

Search spans all indexed source types and connectors that the caller may read. Ask can plan across hybrid search, wiki, code, and live recent-PR retrievers.

Projects narrow relevance; ACLs authorize

A project bundles sources and connectors. An explicit project_idor a human's default project intersects retrieval with those attachments; an empty project returns no sources. Projects never grant access. Workspace, restricted, and project visibility plus source grants are enforced before ranking. API-key agents without a user identity see workspace-visible sources, not user-specific restricted sources. MCP search accepts a project ID, and Ask applies its project to every selected retriever. Standalone search_code, recent_prs, and fetch_source do not currently accept project IDs; they still enforce ACLs, and direct fetch conservatively hides project-visible sources without an active project argument.

Marketing, branding, and video context

Run several focused searches using likely vocabulary such as “brand voice visual identity,” “campaign creative,” and “video production workflow.” Search the wiki for orientation, then use list_skills and fetch_skill to load relevant workflows. Fetch cited sources when exact wording matters. Only pass a project when it actually contains those source or connector attachments.

Recommended agent rule

Use Alexandria as shared company context. Before answering
a company-specific question or making a consequential change, search the
relevant project and source types. For broad questions, inspect index.md and
run several focused search calls; use search_code and recent_prs for code or
recent-change questions. Follow citations with fetch_source when exact wording
matters. When I say "store that knowledge" or we reach a durable decision,
call write_note with a descriptive title, useful Markdown, and tags. Never
store credentials or private tokens.

05 — concepts

Core concepts

Sources & tiers

The registry is the source of truth. Types include note, doc, code, blog, transcript, media, skill, brand_asset, wiki_page, and pointer. Tiers: managed (Alexandria stores content), indexed (content ingested for search), pointer (metadata / URI only — no body required).

Hybrid search & return modes

Vector (Pinecone / Voyage) fused with Postgres full-text search. Filter by source_type, tags, status. Return modes compress responses for agent context windows: raw, headroom, llm_extract.

LLM wiki

An agent-maintained lattice of Markdown (index, entities, concepts, syntheses, log). Prefer the wiki for orientation; use hybrid search for specific facts. Browse at /app/wiki.

Workspaces, roles & plans

Multi-tenant workspaces with member roles (admin vs member). Plans gate members, sources, and monthly searches:

Free — 2 members, 50 sources, 200 searches/mo
Team ($29/mo) — 10 members, 1,000 sources, 5,000 searches/mo
Pro ($99/mo) — 25 members, 10,000 sources, 50,000 searches/mo

06 — REST

API endpoints

All /v1/* routes and /mcp require a Bearer credential. Agents use Authorization: Bearer alx_…; signed-in web requests use a Supabase JWT plus x-workspace-id. Base: https://api.alexandria.page.

Method	Path	Notes
POST	/v1/sources	Create source — title, source_type, tier; content or url for managed/indexed
GET	/v1/sources	List — query: source_type, status, tags, q
GET	/v1/sources/:id	Fetch — query: return_mode, query
GET	/v1/sources/:id/processing	Poll asynchronous evidence, embeddings, and wiki runs
POST	/v1/search	Body: query, project_id, filters, top_k, return_mode
POST	/v1/answer	Ask planner → parallel retrievers → cited synthesis
*	/v1/projects	List/manage project relevance scopes; mutations are admin
*	/v1/connectors	Store connector config/secrets; does not run workers
GET	/v1/wiki/index	Wiki index.md
GET	/v1/wiki/pages	Read page — path required; return_mode, query
POST	/v1/wiki/pages	Write page — path, content
GET	/v1/wiki/log	Maintainer log — query: tail
POST	/v1/notes	Convenience note — title, content (managed note source)
GET	/v1/skills	List skill sources
GET	/v1/skills/:id	Fetch skill — return_mode, query
*	/mcp	MCP Streamable HTTP
GET	/health	Health check (no auth)