git:20260611.280f2a1 to git:20260622.8fea2ad

- **Files** — folders, markdown pages, HTML pages, uploads, and tables.

- **Skills** — modules of agent-usable knowledge: local SKILL.md folders and shareable bundles of sessions and Files.

```yaml

---

name: dd-respond

description: Draft response packets to investor diligence asks

when_to_use: When an investor sends a DD checklist

version: 2.1

mcp_exposed: true

---

```

The folder may contain any number of supporting `.md` files (`examples.md`,

`checklist.md`, etc.) — they all become part of the skill payload. Stash

exposes skills via:

- MCP: `stash_list_skills`, `stash_read_skill`

## Overview

It provides:

- pages organized in nestable folders

- tables (typed columns, rows, CSV import/export, semantic row search)

- session events (with file attachments)

- file uploads (S3-backed; PDF/image text extraction when available)

- Skills for publishing sets of pages, sessions, and files

Design boundary:

- external orchestration layers own multi-agent delegation

- Claude-session memory access should go through the Stash plugin, not side-channel polling

## Base URL

`{{PUBLIC_URL}}`

## Authentication

All endpoints (except registration and a few public lookups) require an API key:

```

Authorization: Bearer mc_xxxxxxxxxxxxx

```

## Quick Start

### 1. Register

```bash

curl -X POST {{BASE_URL}}/api/v1/users/register \

-H "Content-Type: application/json" \

-d '{"name": "my-agent", "description": "A helpful assistant"}'

```

Response includes `api_key` — save it, it's shown only once.

```bash

-H "Authorization: Bearer $API_KEY" \

-H "Content-Type: application/json" \

-d '{"agent_name":"cli","event_type":"note","content":"Hello"}'

```

```bash

-H "Authorization: Bearer $API_KEY" \

-H "Content-Type: application/json" \

-d '{"name":"Notes","content":"# Hello"}'

```

Pass `"folder_id": "<uuid>"` to drop the page into a specific folder;

```bash

-H "Authorization: Bearer $API_KEY" \

-F "file=@./report.pdf"

```

Response includes the file `id`, a signed `url`, and basic metadata. For

PDFs with embedded text and text-based documents, extracted text is

## Route Surfaces

| Surface | Prefix |

|---------|--------|

CRUD verbs are standard: `POST` to create, `GET` list/detail, `PATCH` update,

## Page Content (`content_markdown`)

Pages store markdown. The editor implements a **deliberately small

subset** — agents writing content should stick to what's listed below,

since anything else silently passes through as plain text on render.

### Links

Use ordinary markdown links for everything:

| Target | Shape |

|---|---|

| External URL | `[text](https://…)` |

The viewer renders all three with the same style; an `↗` glyph marks

SPA-routed (same tab, no reload); externals open in a new tab.

There is no `[[...]]` syntax. Use ordinary markdown links with the page's id URL.

### Block elements

| Markdown | Rendered as |

|---|---|

| `# Heading` to `### Heading` (H1–H3) | heading |

| blank line | paragraph break |

| `- item` / `* item` / `+ item` | bullet list |

| `1. item` / `2. item` | ordered list |

| `\| col1 \| col2 \|` followed by `\|---\|---\|` | GitHub-flavored pipe table |

Anything starting with `####` (H4+), `>` (blockquote), triple-backtick

code fences, or `---` (hr) is **not parsed** — the markdown renders

literally. Treat it as unsupported.

### Inline

| Markdown | Rendered as |

|---|---|

| `**bold**` | bold |

| `*italic*` | italic |

| `` `code` `` | inline code |

| `` | image (absolute URLs only) |

| `[](href)` | linked image |

| `[text](url)` | link (see above table) |

Strikethrough (`~~`), underline markup, LaTeX, footnotes, and raw HTML

tags are not supported.

### Authoring from agents

When generating page content programmatically, follow these rules and

you'll round-trip cleanly through edit mode:

1. Never emit `[[…]]` — use the id-URL link form.

2. Never emit relative paths like `[text](foo.md)` or `` —

the renderer treats them as dead and the editor strips them if a

user saves the page.

3. Don't rely on H4 or deeper headings. Restructure with H3 + bold.

## Session Events

```json

{

"agent_name": "cli",

"event_type": "note",

"content": "text body",

"session_id": "optional",

"tool_name": "optional",

"metadata": {},

"attachments": [

{"file_id": "<uuid>", "name": "report.pdf", "content_type": "application/pdf"}

]

}

```

`attachments` entries must reference a previously-uploaded file. The CLI

wrapper (`stash sessions push --attach ./path`) uploads and attaches in one step.

Query/search:

- `GET /events?agent_name=&event_type=&limit=&after=`

- `GET /events/search?q=&limit=`

- `GET /events/{event_id}`

## Files

- `POST /files` — multipart upload (field `file`), 50 MB cap.

- `GET /files` — list.

- `GET /files/{id}` — metadata (with signed URL).

- `GET /files/{id}/text` — extracted text. Response shape:

`{"text": ..., "status": "pending|processing|done|failed", "error": ...}`.

Works for PDFs with embedded text and for plain-text / JSON / XML

uploads. Extraction runs asynchronously after upload — poll this

endpoint until `status` is `done` or `failed`.

- `DELETE /files/{id}` — best-effort S3 cleanup plus DB row delete.

## Rate Limits

- Registration: 5/min

- Login: 10/min

- CLI auth session polling: 60/min

## Tips for Agents

- For extracted text on an uploaded file, poll `GET /files/{id}/text` — it

returns `status` alongside the text so you can distinguish "still

extracting" (`pending`/`processing`) from "done, no text available"

(`done` with `text: null`).

- Attach files to session events rather than embedding base64 — keeps event

payloads small and allows reuse across events.