Skip to content
Developers

Build on your library.

XESO is addressable from your own code and from any MCP-aware client. Query the corpus, read notes, run the research agent, and stream grounded, cited answers from the xeso-1 model — over an OpenAI-compatible REST API or the Model Context Protocol.
OpenAPI spec
MCP setup guide
Get an API key

Connect

REST base URLhttps://xeso.ai/api/v1
MCP server URLhttps://app.xeso.ai/api/mcp
Model idxeso-1
Authenticate every request with a Personal Access Token (PAT) as a bearer token:
curl https://xeso.ai/api/v1/models \
  -H "Authorization: Bearer $XESO_PAT"

# OpenAI-compatible chat, grounded in your library:
curl https://xeso.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $XESO_PAT" \
  -H "Content-Type: application/json" \
  -d '{"model":"xeso-1","messages":[{"role":"user","content":"..."}]}'
Create and revoke tokens at /settings/tokens. Tokens are scoped per user and shown once at creation. The public API requires a paid plan; every answer is grounded in your own notes and carries citations.

REST API

The /api/v1 surface. Full request and response shapes live in the OpenAPI spec.
  • GET/api/v1/healthpublic
    Service liveness probe — version + uptime.
  • GETPOST/api/v1/notesPAT required
    List and create notes (cursor paginated).
  • GETPATCHDELETE/api/v1/notes/{id}PAT required
    Read, edit, or soft-delete a single note. Vaulted segments are 403 vault_locked.
  • POST/api/v1/searchPAT required
    Hybrid search (BM25 + dense) across your notes, returning ranked snippets.
  • GET/api/v1/segmentsPAT required
    List your segments. Read-only in v1; write endpoints land in v1.1.
  • GET/api/v1/modelsPAT required
    List available models (OpenAI-compatible). Today: xeso-1, the grounded completion surface.

MCP tools

Point any MCP-aware client (Cursor, Claude Desktop, …) at https://app.xeso.ai/api/mcp to call these tools against your library. Setup configs are in the MCP guide.
  • searchSearch the user's entire XESO corpus using hybrid (semantic + lexical) ranking. Returns the most relevant passages with citations.
  • search_segmentSearch only within a specific XESO segment (folder). Useful for scoping answers to a single project or topic.
  • read_noteFetch the full content of a single note by ID, including its title, summary, key takeaways, and markdown body.
  • find_notesList recent notes, optionally filtered by segment. Returns note summaries without full bodies.
  • citeResolve a passage ID to a human-readable citation (note title, source URL, and a short excerpt). Use this to render footnotes/links in chat answers.
  • get_factsReturn durable facts the memory layer has learned about the current user (preferences, goals, stated opinions, recurring entities). Use to personalize replies without re-asking.
  • researchRun the multi-step research agent: decomposes a question into sub-queries, retrieves passages for each, and synthesizes a cited report with self-review. Use for multi-hop questions ('compare', 'how did X evolve', 'what does my brain say about Y').
  • generate_flashcardsGenerate grounded flashcards from a specific note the user owns. Returns Anki-importable Q/A pairs with source locations.
  • generate_quizGenerate a grounded multiple-choice quiz from a specific note the user owns.
OpenAPI spec
MCP setup guide
Pricing