# Thalius Hippocampus — developer docs, in one file

> Beta, 5 Oct 2026: endpoints and fields can still change.

# API reference

*API reference*

## Every public endpoint, in one place

The endpoints the Hippocampus web app uses for import, search, answers and reading, with their fields, streaming, jobs and errors.

Beta: fields can still change before general availability.

[Get API access](https://www.thalius.ai/register) · [See an example](https://www.thalius.ai/developers/api#the-shape-of-a-request)

### Resources for AI

- **Coding agent** — Your coding agent (Claude, Cursor, Codex or another) reads our skill file and sets up Hippocampus in your project by itself.
  copy: `Read https://www.thalius.ai/developers/SKILL.md and follow it to set up Hippocampus in this project.` · file: [SKILL.md](https://www.thalius.ai/developers/SKILL.md)
- **API clients** — Your API client (Postman, Insomnia or Bruno) imports every request with example responses; run Sign in first and the token is set for you.
  copy: `https://www.thalius.ai/developers/hippocampus.postman_collection.json` · file: [hippocampus.postman_collection.json](https://www.thalius.ai/developers/hippocampus.postman_collection.json)
- **OpenAPI 3.1** — Client generators, Swagger UI and other API tools read every endpoint from this file, in the standard format.
  copy: `https://www.thalius.ai/developers/openapi.json` · file: [openapi.json](https://www.thalius.ai/developers/openapi.json)
- **Chat assistants** — Your chat assistant (ChatGPT, Claude or Gemini) answers questions about the API from our docs, all in one file.
  copy: `Answer using the Hippocampus docs at https://www.thalius.ai/developers/llms-full.txt` · file: [llms-full.txt](https://www.thalius.ai/developers/llms-full.txt)

*Authentication*

### A signed-in user's token

Every request carries an `Authorization: Bearer <token>` header. The token is the ID token of a signed-in Hippocampus user and lasts about an hour, so a script refreshes it the way any sign-in does. A call reaches only what that user may read.

There are no API keys yet: a script signs in as its own user, with the folders it needs shared to it.

*The surface*

### What the API covers

- **Search and answers** — search returns the passages that match a question, with pages and a link to the original; ask returns a short answer.
- **Documents** — import a source and track how it has been broken into sections.
- **Browse and read** — list folders, read a document's text or download the original.
- **Jobs** — check the status of an import.
- **Errors** — the shape of a failure from each service.

*Illustrative*

### The shape of a request

A document imported, and a question answered from what has been imported. Endpoints and fields are not final.

Illustrative only — not a live contract yet.

**curl**

```bash
curl -X POST /ingest \
  -H "Authorization: Bearer $THALIUS_API_KEY" \
  -F "files=@q3-renewals.pdf"
```

**Python**

```python
client.documents.create(
    file="q3-renewals.pdf",
)
```

**TypeScript**

```javascript
await client.documents.create({
  file: "q3-renewals.pdf",
});
```

*Reference*

### Endpoints

The API has two services, and both take the same token. The core imports, searches and answers; the vault holds folders and documents. Your tenant's addresses are in the Hippocampus app under **Manage tenant → API and MCP**. The default addresses, used in the examples below, are `https://hippocampuscore.thalius.ai` for the core and `https://hippocampusvault.thalius.ai` for the vault.

Every endpoint below has a request in cURL, Python and JavaScript and a trimmed response.

Ids in the examples are shortened.

*Import*

### Import documents

Upload files to the core. Each file is read, split into sections and summarised, then filed in the folder you name. A job tracks the work.

*Core*

#### POST /ingest

Upload one or more files for import into a folder.

**Query**

- `stream` — `true` streams progress as server-sent events; `false` (default) returns a job at once.

**Form fields** (multipart)

- `files` — one or more files: `.pdf`, `.docx`, `.md`, `.markdown`, `.txt`, `.text`. Required.
- `file_metadata` — JSON array with one object per file, in the same order: `folder_name` (folder path) and `tags`.

**Returns** a job: `job_id`, `status` (`processing`, `complete` or `error`), `total_files`, `done`. A file that was already imported comes back with `duplicate: true`.

**cURL**

```bash
curl -sS -X POST "https://hippocampuscore.thalius.ai/ingest" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "files=@MSA-2025.pdf" \
  -F 'file_metadata=[{"folder_name":"contracts/master-agreements","tags":["msa"]}]'
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "processing",
  "message": "Queued 1 file",
  "total_files": 1,
  "done": false
}
```

**Python**

```python
import json, os, requests

with open("MSA-2025.pdf", "rb") as f:
    r = requests.post(
        "https://hippocampuscore.thalius.ai/ingest",
        headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
        files={"files": f},
        data={"file_metadata": json.dumps([{"folder_name": "contracts/master-agreements", "tags": ["msa"]}])},
    )
print(r.json())
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "processing",
  "message": "Queued 1 file",
  "total_files": 1,
  "done": false
}
```

**JavaScript**

```javascript
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("files", new Blob([await readFile("MSA-2025.pdf")]), "MSA-2025.pdf");
form.append("file_metadata", JSON.stringify([{"folder_name": "contracts/master-agreements", "tags": ["msa"]}]));

const res = await fetch("https://hippocampuscore.thalius.ai/ingest", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
  body: form,
});
console.log(await res.json());
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "processing",
  "message": "Queued 1 file",
  "total_files": 1,
  "done": false
}
```

**Streaming**

```bash
curl -sS -N -X POST "https://hippocampuscore.thalius.ai/ingest?stream=true" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "files=@MSA-2025.pdf" \
  -F 'file_metadata=[{"folder_name":"contracts/master-agreements","tags":["msa"]}]'
```

Response:

```text
data: {"event_type":"processing","current_file":"MSA-2025.pdf","current_step":"ocr","message":"Reading the document"}
data: {"event_type":"processing","current_file":"MSA-2025.pdf","document_id":"8c1f0e4a-…","duplicate":false}
data: {"event_type":"complete","successful_files":1}
```

*Core*

#### GET /jobs/{job_id}

Check an import started without streaming. Poll until `done` is `true`.

**Path**

- `job_id` — from the `POST /ingest` response.

**Returns** `status`, `successful`, `failed` and one entry in `results` per file, with its `document_id`.

**cURL**

```bash
curl -sS "https://hippocampuscore.thalius.ai/jobs/c0a9f6d2-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "complete",
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "filename": "MSA-2025.pdf",
      "success": true,
      "document_id": "8c1f0e4a-…",
      "folder_name": "contracts/master-agreements",
      "duplicate": false
    }
  ],
  "done": true
}
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampuscore.thalius.ai/jobs/c0a9f6d2-…",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "complete",
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "filename": "MSA-2025.pdf",
      "success": true,
      "document_id": "8c1f0e4a-…",
      "folder_name": "contracts/master-agreements",
      "duplicate": false
    }
  ],
  "done": true
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampuscore.thalius.ai/jobs/c0a9f6d2-…", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
{
  "job_id": "c0a9f6d2-…",
  "status": "complete",
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "filename": "MSA-2025.pdf",
      "success": true,
      "document_id": "8c1f0e4a-…",
      "folder_name": "contracts/master-agreements",
      "duplicate": false
    }
  ],
  "done": true
}
```

*Search and answers*

### Search and ask

Search returns the passages that match a question, each with its pages and a link to the original. Ask returns a short answer written by the model.

*Core*

#### POST /search

Find the passages that answer a question, ranked.

**Body** (JSON)

- `query` — the question. Required.
- `folder_name` — limit the search to one folder path.
- `tags` — limit it to documents with these tags.

**Returns** `sources`: for each passage `doc_id`, `document_title`, `leaf_title` (the section), `start_page`, `end_page`, `text`, `score` and `deep_link` to the original at that page.

**cURL**

```bash
curl -sS -X POST "https://hippocampuscore.thalius.ai/search" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period for termination?","folder_name":"contracts/master-agreements"}'
```

Response:

```json
{
  "sources": [
    {
      "doc_id": "8c1f0e4a-…",
      "document_title": "Master Services Agreement 2025",
      "leaf_title": "12. Term and Termination",
      "start_page": 14,
      "end_page": 15,
      "score": 0.91,
      "text": "Either party may terminate this Agreement on ninety (90) days' written notice…",
      "deep_link": "/documents/5b7d2c90-….pdf#page=14"
    }
  ]
}
```

**Python**

```python
import os, requests

r = requests.post(
    "https://hippocampuscore.thalius.ai/search",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
    json={
        "query": "What is the notice period for termination?",
        "folder_name": "contracts/master-agreements"
    },
)
print(r.json())
```

Response:

```json
{
  "sources": [
    {
      "doc_id": "8c1f0e4a-…",
      "document_title": "Master Services Agreement 2025",
      "leaf_title": "12. Term and Termination",
      "start_page": 14,
      "end_page": 15,
      "score": 0.91,
      "text": "Either party may terminate this Agreement on ninety (90) days' written notice…",
      "deep_link": "/documents/5b7d2c90-….pdf#page=14"
    }
  ]
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampuscore.thalius.ai/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "What is the notice period for termination?",
    "folder_name": "contracts/master-agreements"
  }),
});
console.log(await res.json());
```

Response:

```json
{
  "sources": [
    {
      "doc_id": "8c1f0e4a-…",
      "document_title": "Master Services Agreement 2025",
      "leaf_title": "12. Term and Termination",
      "start_page": 14,
      "end_page": 15,
      "score": 0.91,
      "text": "Either party may terminate this Agreement on ninety (90) days' written notice…",
      "deep_link": "/documents/5b7d2c90-….pdf#page=14"
    }
  ]
}
```

*Core*

#### POST /ask

Get a short answer to a question, written from the matching passages.

**Body** (JSON)

- `query` — the question. Required.
- `folder_name`, `tags` — as in search.

**Returns** `answer`, `reasoning` and `confidence`. The passages are not returned; call search for them.

**cURL**

```bash
curl -sS -X POST "https://hippocampuscore.thalius.ai/ask" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period for termination?","folder_name":"contracts/master-agreements"}'
```

Response:

```json
{
  "answer": "Either party may terminate on 90 days' written notice (section 12.2).",
  "reasoning": "Section 12.2 of the Master Services Agreement states…",
  "confidence": 0.86
}
```

**Python**

```python
import os, requests

r = requests.post(
    "https://hippocampuscore.thalius.ai/ask",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
    json={
        "query": "What is the notice period for termination?",
        "folder_name": "contracts/master-agreements"
    },
)
print(r.json())
```

Response:

```json
{
  "answer": "Either party may terminate on 90 days' written notice (section 12.2).",
  "reasoning": "Section 12.2 of the Master Services Agreement states…",
  "confidence": 0.86
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampuscore.thalius.ai/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "What is the notice period for termination?",
    "folder_name": "contracts/master-agreements"
  }),
});
console.log(await res.json());
```

Response:

```json
{
  "answer": "Either party may terminate on 90 days' written notice (section 12.2).",
  "reasoning": "Section 12.2 of the Master Services Agreement states…",
  "confidence": 0.86
}
```

*Browse*

### Folders and what they hold

Folder summaries come from the core; folders and document lists come from the vault.

*Core*

#### GET /folders/summary

Read what a folder holds, as written at import, without running a search.

**Query**

- `folder_name` — the folder path. Required.

**Returns** `status` (`ok`, `none` or `unavailable`) and `folder_summary` with `title`, `description` and `content`.

**cURL**

```bash
curl -sS "https://hippocampuscore.thalius.ai/folders/summary?folder_name=contracts/master-agreements" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
{
  "status": "ok",
  "folder_summary": {
    "folder": "contracts/master-agreements",
    "title": "Master agreements",
    "description": "Signed MSAs with customers and suppliers, 2019–2025.",
    "content": "- Master Services Agreement 2025: term, termination, liability caps…",
    "truncated": false
  }
}
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampuscore.thalius.ai/folders/summary?folder_name=contracts/master-agreements",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
{
  "status": "ok",
  "folder_summary": {
    "folder": "contracts/master-agreements",
    "title": "Master agreements",
    "description": "Signed MSAs with customers and suppliers, 2019–2025.",
    "content": "- Master Services Agreement 2025: term, termination, liability caps…",
    "truncated": false
  }
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampuscore.thalius.ai/folders/summary?folder_name=contracts/master-agreements", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
{
  "status": "ok",
  "folder_summary": {
    "folder": "contracts/master-agreements",
    "title": "Master agreements",
    "description": "Signed MSAs with customers and suppliers, 2019–2025.",
    "content": "- Master Services Agreement 2025: term, termination, liability caps…",
    "truncated": false
  }
}
```

*Vault*

#### GET /folders

List the top-level folders, or the folders inside one folder.

**Query**

- `parentFolderId` — the folder to list. Leave it out for the top level.

**Returns** an array of folders: `id`, `name`, `parentFolderId`, `createdAt`, `updatedAt`.

**cURL**

```bash
curl -sS "https://hippocampusvault.thalius.ai/folders?parentFolderId=0c25a285-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
[
  {
    "id": "0144f7ed-…",
    "name": "Onboarding notes",
    "parentFolderId": "0c25a285-…",
    "createdAt": "2026-09-08T09:15:16.000Z",
    "updatedAt": "2026-09-08T09:15:16.000Z"
  }
]
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/folders?parentFolderId=0c25a285-…",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
[
  {
    "id": "0144f7ed-…",
    "name": "Onboarding notes",
    "parentFolderId": "0c25a285-…",
    "createdAt": "2026-09-08T09:15:16.000Z",
    "updatedAt": "2026-09-08T09:15:16.000Z"
  }
]
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/folders?parentFolderId=0c25a285-…", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
[
  {
    "id": "0144f7ed-…",
    "name": "Onboarding notes",
    "parentFolderId": "0c25a285-…",
    "createdAt": "2026-09-08T09:15:16.000Z",
    "updatedAt": "2026-09-08T09:15:16.000Z"
  }
]
```

*Vault*

#### GET /folders/{id}

One folder. With `include=true` the same call also returns the folders above it, its documents and its subfolders.

**Path**

- `id` — the folder id.

**Query**

- `include` — `true` to add `ancestors`, `documents` and `subfolders`.

**cURL**

```bash
curl -sS "https://hippocampusvault.thalius.ai/folders/0144f7ed-…?include=true" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
{
  "id": "0144f7ed-…",
  "name": "Onboarding notes",
  "parentFolderId": "0c25a285-…",
  "ancestors": [
    {
      "id": "0c25a285-…",
      "name": "HR"
    }
  ],
  "documents": [
    {
      "id": "3c76ff09-…",
      "name": "comments.md",
      "contentType": "text/markdown",
      "folderId": "0144f7ed-…",
      "version": 1
    }
  ],
  "subfolders": [
    {
      "id": "9e2a…",
      "name": "_hippocampus"
    }
  ]
}
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/folders/0144f7ed-…?include=true",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
{
  "id": "0144f7ed-…",
  "name": "Onboarding notes",
  "parentFolderId": "0c25a285-…",
  "ancestors": [
    {
      "id": "0c25a285-…",
      "name": "HR"
    }
  ],
  "documents": [
    {
      "id": "3c76ff09-…",
      "name": "comments.md",
      "contentType": "text/markdown",
      "folderId": "0144f7ed-…",
      "version": 1
    }
  ],
  "subfolders": [
    {
      "id": "9e2a…",
      "name": "_hippocampus"
    }
  ]
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/folders/0144f7ed-…?include=true", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
{
  "id": "0144f7ed-…",
  "name": "Onboarding notes",
  "parentFolderId": "0c25a285-…",
  "ancestors": [
    {
      "id": "0c25a285-…",
      "name": "HR"
    }
  ],
  "documents": [
    {
      "id": "3c76ff09-…",
      "name": "comments.md",
      "contentType": "text/markdown",
      "folderId": "0144f7ed-…",
      "version": 1
    }
  ],
  "subfolders": [
    {
      "id": "9e2a…",
      "name": "_hippocampus"
    }
  ]
}
```

*Vault*

#### GET /documents

List the documents in a folder, without their content.

**Query**

- `folderId` — the folder. Leave it out for the top level.
- `tag` — only documents with this tag.

**Returns** an array: `id`, `name`, `contentType`, `folderId`, `version`, `createdAt`, `updatedAt`.

**cURL**

```bash
curl -sS "https://hippocampusvault.thalius.ai/documents?folderId=0144f7ed-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "folderId": "0144f7ed-…",
    "version": 1,
    "createdAt": "2026-09-08T09:15:17.000Z"
  }
]
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/documents?folderId=0144f7ed-…",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "folderId": "0144f7ed-…",
    "version": 1,
    "createdAt": "2026-09-08T09:15:17.000Z"
  }
]
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/documents?folderId=0144f7ed-…", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "folderId": "0144f7ed-…",
    "version": 1,
    "createdAt": "2026-09-08T09:15:17.000Z"
  }
]
```

*Read*

### Read documents

The vault returns a document's text, its tags and the original file.

*Vault*

#### GET /documents/{id}

One document's details. A text document also carries its `content` as Markdown.

**Path**

- `id` — the document id.

**Returns** `id`, `name`, `contentType`, `size`, `version`, `folderId`, `createdAt` and, for text, `content`.

**cURL**

```bash
curl -sS "https://hippocampusvault.thalius.ai/documents/0001b85f-…" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
{
  "id": "0001b85f-…",
  "name": "Onboarding notes.md",
  "contentType": "text/markdown",
  "size": 510,
  "version": 1,
  "folderId": "d3f3ed56-…",
  "createdAt": "2026-09-08T09:15:17.000Z",
  "content": "---\ntype: document\ntitle: Onboarding notes\n---\n…"
}
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/documents/0001b85f-…",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
{
  "id": "0001b85f-…",
  "name": "Onboarding notes.md",
  "contentType": "text/markdown",
  "size": 510,
  "version": 1,
  "folderId": "d3f3ed56-…",
  "createdAt": "2026-09-08T09:15:17.000Z",
  "content": "---\ntype: document\ntitle: Onboarding notes\n---\n…"
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/documents/0001b85f-…", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
{
  "id": "0001b85f-…",
  "name": "Onboarding notes.md",
  "contentType": "text/markdown",
  "size": 510,
  "version": 1,
  "folderId": "d3f3ed56-…",
  "createdAt": "2026-09-08T09:15:17.000Z",
  "content": "---\ntype: document\ntitle: Onboarding notes\n---\n…"
}
```

*Vault*

#### POST /documents/batch

Up to 100 documents, with content, in one call.

**Body** (JSON)

- `ids` — up to 100 document ids. Required.

**Returns** an array of documents. Ids that do not exist or that you may not read are left out.

**cURL**

```bash
curl -sS -X POST "https://hippocampusvault.thalius.ai/documents/batch" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["0001b85f-…","3c76ff09-…"]}'
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "content": "---\ntype: document\n…"
  },
  {
    "id": "3c76ff09-…",
    "name": "comments.md",
    "contentType": "text/markdown",
    "content": "…"
  }
]
```

**Python**

```python
import os, requests

r = requests.post(
    "https://hippocampusvault.thalius.ai/documents/batch",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
    json={
        "ids": [
            "0001b85f-…",
            "3c76ff09-…"
        ]
    },
)
print(r.json())
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "content": "---\ntype: document\n…"
  },
  {
    "id": "3c76ff09-…",
    "name": "comments.md",
    "contentType": "text/markdown",
    "content": "…"
  }
]
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/documents/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ids": [
      "0001b85f-…",
      "3c76ff09-…"
    ]
  }),
});
console.log(await res.json());
```

Response:

```json
[
  {
    "id": "0001b85f-…",
    "name": "Onboarding notes.md",
    "contentType": "text/markdown",
    "content": "---\ntype: document\n…"
  },
  {
    "id": "3c76ff09-…",
    "name": "comments.md",
    "contentType": "text/markdown",
    "content": "…"
  }
]
```

*Vault*

#### GET /documents/{id}/content

The stored file itself: the original PDF, an image or Markdown, with its own content type.

**Path**

- `id` — the document id, for example the one in a search result's `deep_link`.

**cURL**

```bash
curl -sS -o original.pdf "https://hippocampusvault.thalius.ai/documents/5b7d2c90-…/content" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/documents/5b7d2c90-…/content",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
open("original.pdf", "wb").write(r.content)
```

**JavaScript**

```javascript
import { writeFile } from "node:fs/promises";

const res = await fetch("https://hippocampusvault.thalius.ai/documents/5b7d2c90-…/content", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
await writeFile("original.pdf", Buffer.from(await res.arrayBuffer()));
```

*Vault*

#### GET /documents/{id}/tags

A document's tags.

**Path**

- `id` — the document id.

**Returns** `tags`.

**cURL**

```bash
curl -sS "https://hippocampusvault.thalius.ai/documents/0001b85f-…/tags" \
  -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

Response:

```json
{
  "tags": [
    "onboarding",
    "hr"
  ]
}
```

**Python**

```python
import os, requests

r = requests.get(
    "https://hippocampusvault.thalius.ai/documents/0001b85f-…/tags",
    headers={"Authorization": f"Bearer {os.environ['HIPPOCAMPUS_TOKEN']}"},
)
print(r.json())
```

Response:

```json
{
  "tags": [
    "onboarding",
    "hr"
  ]
}
```

**JavaScript**

```javascript
const res = await fetch("https://hippocampusvault.thalius.ai/documents/0001b85f-…/tags", {
  headers: { Authorization: `Bearer ${process.env.HIPPOCAMPUS_TOKEN}` },
});
console.log(await res.json());
```

Response:

```json
{
  "tags": [
    "onboarding",
    "hr"
  ]
}
```

*Errors*

### When a call fails

The core answers with `detail`. The vault answers with `message`, or with `error` when the token is missing or not valid.

- `401` — the token is missing, expired or not valid. Sign in again.
- `403` — the user may not read or change that folder.
- `404` — not found, or not readable by this user.
- `409` — the document changed since you read it.
- `422` — a field is missing or has the wrong type.

**Core 401**

```json
{
  "detail": "Not authenticated"
}
```

**Core 422**

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "query"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

**Vault 401**

```json
{
  "error": "unauthenticated"
}
```

**Vault 404**

```json
{
  "statusCode": 404,
  "message": "not_found"
}
```

*Clients*

*For now*

curl and our MCP server both work today. Official Python and TypeScript SDKs are planned before general availability.

[MCP](https://www.thalius.ai/developers/mcp) · [Web](https://www.thalius.ai/developers/workspace)

### Want early access to the API?

We are onboarding design partners now.

[Get API access](https://www.thalius.ai/register)

---

# MCP

*MCP*

## Connect an agent over MCP

The MCP server speaks streamable HTTP and signs clients in with OAuth, so a client needs no pasted token: the first call answers `401`, the client reads the protected-resource metadata, registers itself and opens the sign-in page. It is in beta: sign-in on the shared cloud is being completed.

### Resources for AI

- **Claude Code** — Claude Code adds the Hippocampus server with one command and opens the sign-in the first time you use it.
  copy: `claude mcp add --transport http --scope user hippocampus https://hippocampusmcp.thalius.ai/mcp` · file: [.mcp.json](https://www.thalius.ai/developers/mcp-config/claude-code.json)
- **Cursor** — Cursor opens and adds the Hippocampus server in one click; sign in when it asks.
  [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=hippocampus&config=eyJ1cmwiOiJodHRwczovL2hpcHBvY2FtcHVzbWNwLnRoYWxpdXMuYWkvbWNwIn0=) · file: [mcp.json](https://www.thalius.ai/developers/mcp-config/cursor.json)
- **VS Code** — VS Code opens and adds the server for its built-in agent; with Cline, paste the address under Remote Servers.
  [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22hippocampus%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//hippocampusmcp.thalius.ai/mcp%22%7D) · file: [mcp.json](https://www.thalius.ai/developers/mcp-config/vscode.json)
- **Coding agent** — Your coding agent (Claude, Cursor, Codex or another) reads our skill file and connects to Hippocampus by itself.
  copy: `Read https://www.thalius.ai/developers/SKILL.md and follow it to set up Hippocampus in this project.` · file: [SKILL.md](https://www.thalius.ai/developers/SKILL.md)
- **Chat apps** — In Claude, ChatGPT or Gemini, add a custom connector with this address; the steps for each are below.
  copy: `https://hippocampusmcp.thalius.ai/mcp`

*Tools*

### What an agent can do

- **Ask & search** — scoped to a folder, tags or a document.
- **Browse** — folders, tags and the documents in them.
- **Read** — a document's Markdown and metadata.
- **Import** — files, and follow the job.

*Connect a client*

### Set up your client

Your tenant's MCP address is in the Hippocampus app under **Manage tenant → API and MCP**. The default address is `https://hippocampusmcp.thalius.ai/mcp`, and the examples below use it.

None of the clients needs a pasted token: the first time a client calls the server, it opens a browser window where you sign in to Hippocampus.

Menus move between client versions. If a step looks different, follow the client's own guide to adding a remote MCP server.

#### Claude

**claude.ai and Claude Desktop**

1. Open **Customize → Connectors**.
2. Click **+ Add**, then **Add custom connector**.
3. Enter the name `hippocampus` and your MCP address, then click **Continue**.
4. Keep the sign-in settings Claude detects, click **Continue**, then **Add**.
5. Sign in to Hippocampus in the browser window that opens.

On Team and Enterprise plans an Owner adds the connector under **Organization settings → Connectors**, and members click **Connect**. The Free plan allows one custom connector.

**Claude Code**

Add the server from the terminal, then sign in with `claude mcp login hippocampus` or with `/mcp` inside Claude Code.

**claude.ai**

```text
Customize → Connectors → + Add → Add custom connector
Name: hippocampus
URL:  https://hippocampusmcp.thalius.ai/mcp
```

**Claude Code**

```bash
claude mcp add --transport http --scope user \
  hippocampus https://hippocampusmcp.thalius.ai/mcp
claude mcp login hippocampus
```

**.mcp.json**

```json
{
  "mcpServers": {
    "hippocampus": {
      "type": "http",
      "url": "https://hippocampusmcp.thalius.ai/mcp"
    }
  }
}
```

#### ChatGPT

1. In ChatGPT on the web, open **Settings** and switch on **Developer mode**. It is under **Security and login**, or under **Apps → Advanced settings** in a Business, Enterprise or Edu workspace, where an admin allows it first.
2. Create an app for the MCP server: enter the name `hippocampus` and your MCP address, and choose **OAuth** as the authentication.
3. Sign in to Hippocampus when ChatGPT asks.
4. In a chat, open **+ → Developer mode** and select `hippocampus`.

Developer mode works on the web, not on the Free plan. On a Pro plan ChatGPT allows read tools only, so Import is not available there.

**App settings**

```text
Name:            hippocampus
MCP server URL:  https://hippocampusmcp.thalius.ai/mcp
Authentication:  OAuth
```

#### Gemini

**Gemini CLI**

Add the server with the command, then start `gemini`. The CLI opens the sign-in on its first call to the server; `/mcp auth hippocampus` signs in again.

**Gemini app**

Open **Settings → Connected Apps**, click **Add a custom app** under Custom apps, enter your MCP address and sign in. Custom apps are available for personal Google accounts in the US, in English, with Keep Activity on.

**Gemini CLI**

```bash
gemini mcp add --transport http -s user \
  hippocampus https://hippocampusmcp.thalius.ai/mcp
```

**settings.json**

```json
{
  "mcpServers": {
    "hippocampus": {
      "type": "http",
      "url": "https://hippocampusmcp.thalius.ai/mcp"
    }
  }
}
```

#### Cursor

1. Add the server to `~/.cursor/mcp.json` to use it in every project, or to `.cursor/mcp.json` in one project.
2. Cursor lists the server in its MCP settings, where you can switch it on or off.
3. Sign in to Hippocampus when Cursor asks.

**mcp.json**

```json
{
  "mcpServers": {
    "hippocampus": {
      "url": "https://hippocampusmcp.thalius.ai/mcp"
    }
  }
}
```

#### Devin Desktop (Windsurf)

Windsurf is now called Devin Desktop.

1. In the agent panel, open the **…** menu, choose **MCPs**, then **Open MCP config file**.
2. Add the server under `mcpServers` and save the file.
3. Sign in to Hippocampus when asked.

The file is `~/.config/devin/mcp_config.json`; builds from before the rename use `~/.codeium/windsurf/mcp_config.json`. On Enterprise plans an admin switches MCP on first.

**mcp_config.json**

```json
{
  "mcpServers": {
    "hippocampus": {
      "serverUrl": "https://hippocampusmcp.thalius.ai/mcp"
    }
  }
}
```

**Devin CLI**

```bash
devin mcp add -s user hippocampus \
  https://hippocampusmcp.thalius.ai/mcp
devin mcp login hippocampus
```

#### VS Code with Cline

1. In the Cline panel, open **MCP Servers**, then the **Remote Servers** tab.
2. Enter the name `hippocampus` and your MCP address, keep **Streamable HTTP**, and click **Add Server**.
3. When Cline shows **Authenticate** next to the server, click it and sign in to Hippocampus.

To edit the file instead, click **Configure MCP Servers** and set `"type": "streamableHttp"`. Without it, Cline uses the older SSE transport.

VS Code's own agent, without Cline, reads the server from `.vscode/mcp.json`.

**Cline**

```json
{
  "mcpServers": {
    "hippocampus": {
      "type": "streamableHttp",
      "url": "https://hippocampusmcp.thalius.ai/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**VS Code**

```json
{
  "servers": {
    "hippocampus": {
      "type": "http",
      "url": "https://hippocampusmcp.thalius.ai/mcp"
    }
  }
}
```

### Tools

*The full list from the MCP server.*

| Tool | What it does | Reads or writes | Inputs | Returns | Try asking |
|---|---|---|---|---|---|
| `hippocampus_ask` | Ask a question | read | `query` (required); `folder_name` or `document_id` to scope it | An answer with its reasoning and a confidence score | What is the notice period in our supplier contracts? |
| `hippocampus_search` | Search documents | read | `query` (required); `folder_name`; `tags` with `tag_mode` (`all` or `any`) | The most relevant passages, with page references and deep links | Find the passages about termination for convenience. |
| `hippocampus_list_folders` | List all folders | read | — | The folder names you can see | Which folders are in Hippocampus? |
| `hippocampus_list_documents_by_folder` | List documents by folder | read | `folder_name` (required; nested paths work) | The documents in that folder: id, title, tags | List the documents in contracts/master-agreements. |
| `hippocampus_list_tags` | List all tags | read | — | The tags you can see | Which tags are used? |
| `hippocampus_list_documents_by_tag` | List documents by tag | read | `tag_name` (required) | The documents with that tag: id, title, tags | Show me the documents tagged msa. |
| `hippocampus_get_document_markdown` | Get document Markdown | read | `document_id` (required) | The document's full text as Markdown | Open the Master Services Agreement and summarise section 12. |
| `hippocampus_get_document_metadata` | Get document metadata | read | `document_id` (required) | Title, access level, tags, creation date | When was this document added, and how is it tagged? |
| `hippocampus_ingest` | Ingest documents | write | `file_paths` — paths on the server's own disk; `file_metadata` with `folder_name` per file | A `job_id`; the import runs in the background | (server-side setups only) |
| `hippocampus_job_status` | Check ingestion job status | read | `job_id` (required) | Status, and per file the document id and whether it succeeded | Is the import finished? |
| `hippocampus_health` | Health check | read | — | Whether the API answers | — |
| `hippocampus_delete_documents` | Delete documents (off by default) | write, destructive | `doc_ids` (1–100) | Per document, what was deleted | — |

Import through MCP takes file paths on the server's own disk, so it works only where the MCP server runs next to the files. To upload from your own machine, use the API's `POST /ingest`.

**Resources:** `hippocampus://folders`, `hippocampus://folders/{folder_name}`, `hippocampus://tags`, `hippocampus://tags/{tag_name}`, `hippocampus://documents/{document_id}/content`

**Suggested order** (from the server's own instructions): browse folders or tags → list the documents in one → search for passages → ask a focused question, scoped to a folder or a document.

*Troubleshooting*

### Before you open an issue

**What does a 401 on the first call mean?**
The client has no session yet. It should read the protected-resource metadata and open the sign-in page on its own — no pasted token needed.

**Sign-in isn't completing on the shared cloud.**
That flow is still being finished for the beta.

### Want to try it?

Connect your agent once you have workspace access.

[Get access](https://www.thalius.ai/register)

### One-click install

- **Cursor:** `cursor://anysphere.cursor-deeplink/mcp/install?name=hippocampus&config=eyJ1cmwiOiJodHRwczovL2hpcHBvY2FtcHVzbWNwLnRoYWxpdXMuYWkvbWNwIn0=`
- **VS Code:** `vscode:mcp/install?%7B%22name%22%3A%22hippocampus%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//hippocampusmcp.thalius.ai/mcp%22%7D`

These open the client and add the server. The site's buttons accept web links only today, so placing them as buttons needs a small change to the site.

---

# Skill for coding agents

# Hippocampus

Hippocampus turns a company's documents into a layered knowledge base. Search finds the passages that answer a question, each with its pages and a link to the original; ask returns a short answer.

## Before you start

- **Access:** API access gives you a user for your script in a Hippocampus tenant. There are no API keys yet.
- **Addresses:** the tenant's addresses are in the Hippocampus app under Manage tenant → API and MCP. Defaults: core `https://hippocampuscore.thalius.ai`, vault `https://hippocampusvault.thalius.ai`, MCP `https://hippocampusmcp.thalius.ai/mcp`.
- **Token:** every REST call sends `Authorization: Bearer $HIPPOCAMPUS_TOKEN`, the ID token of the signed-in script user. It lasts about an hour; on a `401`, sign in again.

## Connect over MCP (preferred for agents)

The MCP server speaks streamable HTTP and signs in with OAuth in the browser: no token to paste.

```bash
claude mcp add --transport http --scope user hippocampus https://hippocampusmcp.thalius.ai/mcp
claude mcp login hippocampus
```

Other clients: https://www.thalius.ai/developers/mcp

Tools: `hippocampus_ask`, `hippocampus_search`, `hippocampus_list_folders`, `hippocampus_list_documents_by_folder`, `hippocampus_list_tags`, `hippocampus_list_documents_by_tag`, `hippocampus_get_document_markdown`, `hippocampus_get_document_metadata`, `hippocampus_ingest`, `hippocampus_job_status`, `hippocampus_health`. Work in this order: list folders or tags → list documents in one → `hippocampus_search` for passages → `hippocampus_ask`, scoped by `folder_name` or `document_id`. MCP import (`hippocampus_ingest`) takes paths on the server's own disk: to upload a local file, use REST `POST /ingest`.

## REST: the four calls

```bash
# 1. Import (stream=true shows progress; without it, poll GET /jobs/{job_id} until done is true)
curl -sS -N -X POST "https://hippocampuscore.thalius.ai/ingest?stream=true" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "files=@contract.pdf" -F 'file_metadata=[{"folder_name":"contracts","tags":[]}]'

# 2. Search: passages with pages and a deep link to the original
curl -sS -X POST "https://hippocampuscore.thalius.ai/search" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period?","folder_name":"contracts"}'

# 3. Ask: a short answer (no passages; use search for those)
curl -sS -X POST "https://hippocampuscore.thalius.ai/ask" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period?","folder_name":"contracts"}'

# 4. Read a document's text (vault)
curl -sS "https://hippocampusvault.thalius.ai/documents/<document-id>" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

## Gotchas

- `folder_name` is a folder path such as `contracts/master-agreements`; vault calls take folder and document ids (UUIDs).
- `/ask` returns `answer`, `reasoning` and `confidence` only. Cite from `/search`.
- An ingest job is finished when `status` is `complete` (not `completed`), or simply when `done` is `true`.
- A streamed import may end with `{"event_type":"error","error":"stream_stalled"}`: the import keeps running. Check the job instead of uploading again.
- Results contain only what the signed-in user may read; a `404` from the vault can mean "not readable".
- Errors: the core answers `{"detail": …}`, the vault `{"message": …}` (or `{"error": "unauthenticated"}` on a bad token).
- The API is in beta: fields can still change. Do not invent SDK calls; there are no official SDKs yet.

## Reference

- API reference: https://www.thalius.ai/developers/api (Markdown: https://www.thalius.ai/developers/api.md)
- OpenAPI: https://www.thalius.ai/developers/openapi.json · Postman: https://www.thalius.ai/developers/hippocampus.postman_collection.json
- MCP: https://www.thalius.ai/developers/mcp (Markdown: https://www.thalius.ai/developers/mcp.md)
- Security and data handling: https://www.thalius.ai/security