API, MCP & CLI Reference
Everything in your library is reachable three ways: the MCP server (what your AI tool talks to), the REST API (what scripts talk to), and the pull CLI (what writes local copies into your project). All three authenticate with the same API token.
- Base URL:
https://www.aistoragedepot.com - Auth: an API token, sent as
Authorization: Bearer <token>(or, for the MCP endpoint,?token=<token>). - Free for individuals — 2,500 pulls/month included (30,000 on Individual Plus), then a reduced-speed lane of 2 pulls/hour until the monthly reset (never a hard block); plus an anti-abuse rate limit. A "pull" is a content read (see Pull allowances).
Getting a token
- Settings → API tokens → New token. Give it a name.
- Copy it now — it's shown once. We store only a SHA-256 hash, so we can't show it again.
- Revoke any token from the same screen; revocation cuts off access instantly, everywhere it was used.
Tokens act as you. A Bearer request sees only your own libraries — your personal library plus the teams and companies you belong to. The prebuilt AIStorageDepot Library is for browsing in the app and is deliberately invisible to tokens, so "use my code-review prompt" always resolves to your prompt.
Managing tokens is session-only (you must be signed in the browser). A leaked token can't mint or revoke tokens.
Deactivated items are hidden from tokens. Any item you've deactivated (💤) is skipped by every token surface — MCP, REST, and
pull— so your AI never sees it. A REST read can opt back in with?includeMuted=1.
MCP server (what your AI connects to)
The MCP server is the primary way your AI reaches your library. It's the same server whether you connect the hosted URL or run the stdio package — same prompts, resources, and tools.
Two ways to connect
Hosted (remote) — for connector-based clients
https://www.aistoragedepot.com/api/mcp?token=YOUR_TOKEN
Speaks MCP over Streamable HTTP (stateless JSON-RPC): the client POSTs a JSON-RPC request and gets a JSON response. You can send the token as ?token=… or an Authorization: Bearer … header — prefer the header where your client supports it, so the token stays out of URLs.
For Claude Code, use the standard install instead — the same command the Connect page generates (-s user = available in every project):
claude mcp add -s user aisd --env AISD_TOKEN=YOUR_TOKEN -- cmd /c npx -y "@aistoragedepot/mcp"
(Windows form; on macOS/Linux drop the cmd /c — … -- npx -y @aistoragedepot/mcp.)
Local (stdio) — for desktop apps like Claude Desktop
{
"mcpServers": {
"aisd": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@aistoragedepot/mcp"],
"env": { "AISD_TOKEN": "YOUR_TOKEN" }
}
}
}
On macOS/Linux the command is just "npx" with args: ["-y", "@aistoragedepot/mcp"]. On Windows you must wrap it in cmd /c (as above) — Windows can't spawn npx directly. The Connect page generates the correct config for your OS and tool; prefer that over hand-editing.
What the server exposes
| MCP capability | What your AI gets |
|---|---|
| Tools | search_library, get_item (below) |
| Resources | Every item as aisd://item/<id>, with its title, type, tags, and MIME type |
| Prompts | The items you've marked / in the app (any type), exposed as native MCP prompts — prompt-format items carry their [placeholders] as fill-in arguments; other types insert their content |
Tools:
search_library—{ "query": "keyword" }. Searches titles, bodies, tags, and categories across your own libraries. Returns matches with theiraisd://item/<id>URIs. (Needs ≥ 2 characters.)get_item—{ "id": "<id or aisd://item/<id>>" }. Returns the full body of one item.
Two automatic headers keep agents honest: a fill-in template (a prompt with [fields]) is served with a "collect values before use" header naming its fields, and a stale copy (its source has a newer version) is served with a "newer version exists" heads-up — list descriptions carry a matching ⬆ newer version available (vN) flag. Skipping the version in the app silences both until the source moves again.
Server details: server name aisd, protocol version 2024-11-05. Deactivated items and the example libraries are excluded. Individuals get 2,500 pulls/month free, 30,000 on Plus (throttled past it, not blocked); the anti-abuse limit returns JSON-RPC error -32003 with HTTP 429. A token that is present but invalid returns -32001 with HTTP 401. With no token at all, the server runs in free sample mode — a read-only view of the prebuilt AIStorageDepot Library, subject to our Terms; add a token to switch to your own libraries.
Raw JSON-RPC example
curl -s "https://www.aistoragedepot.com/api/mcp?token=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"search_library","arguments":{"query":"code review"}}}'
Supported methods: initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get. Batched requests (a JSON array) are supported; notifications get a 202 with no body.
Only tools/call, resources/read, and prompts/get count as pulls; the handshake and */list methods are never metered or slowed. At quota your AI can still connect and list — only content reads drop to the reduced-speed lane (2/hour), returned as JSON-RPC -32003 with HTTP 429.
pull CLI (local copies in your project)
pull is optional. MCP already serves your library live; pull writes local files into your project or user config so items show up as typed /slash commands even when your tool isn't connected over MCP.
npx -y @aistoragedepot/mcp pull --token=YOUR_TOKEN --workspaces=all --to=all --types=skill
On Windows PowerShell, quote the scoped package name:
npx -y "@aistoragedepot/mcp" pull --token=YOUR_TOKEN --workspaces=all --to=all --types=skill
Flags
| Flag | Meaning |
|---|---|
--token=YOUR_TOKEN | Your API token. No space after the = — --token= abc leaves the token empty. |
--workspaces=all | Include team/company libraries too, not just your personal one. |
--to=all | Write commands for every detected tool on the machine. |
--types=skill | Default. Pull skills only (see the note below). Use --types=all to include prompts. |
When you actually need pull
You don't need pull for slash commands — mark an item / in the app and it's live in your menu over MCP. pull is for local copies: they need no token, work offline, and cover tools that don't surface MCP prompts as typed commands. Anything that's both marked / and pulled appears twice in your menu ((user) = the frozen file, (MCP) = live — prefer (MCP)). Re-run pull any time to refresh the local copies; it only touches AIStorageDepot files. Each run ends with a summary of any items that are behind their source, since pulled files don't update themselves.
The @aistoragedepot/mcp package is the same one you point Claude Desktop at as a stdio server — with the pull subcommand it becomes the CLI.
REST API
All REST endpoints are under /api. Send Authorization: Bearer YOUR_TOKEN. Reads via a Bearer token get the agent view — your own libraries only, deactivated items excluded.
What counts as a pull: only content reads made with a token — GET /api/search, GET /api/items/{id}/body, GET /api/items/{id}/resolved, and GET /api/items/{id}/source-preview. Listing endpoints, writes, and settings calls never count toward your monthly pulls.
Read your library
| Method & path | Purpose |
|---|---|
GET /api/health | Liveness + DB check. Anonymous. Returns {"ok":true} (or 503). |
GET /api/workspaces | The libraries you can see. Via token: your own only (the prebuilt library is excluded). |
GET /api/library?workspace=<id> | Full payload for one library (or your default). Add ?includeMuted=1 to include deactivated items. |
GET /api/search?q=<term>&… | Search across your libraries. Counts as a pull via a token. |
GET /api/items/{id}/body | One item's current content. Counts as a pull via a token. |
GET /api/items/{id}/resolved | The body with @aisd:<slug> references inlined (access-checked). Counts as a pull via a token. |
GET /api/types · GET /api/categories | Your item types and categories. |
Create & manage items
| Method & path | Purpose |
|---|---|
POST /api/items | Create an item. Body: { workspaceId, typeId, title, body, categoryId?, tags? }. workspaceId and typeId are required. |
PATCH/DELETE /api/items/{id} | Edit or delete one item. (To read content, use /body or /resolved above.) |
GET /api/items/{id}/versions/{v} | One specific version's content. (DELETE /api/items/{id}/versions clears history, keeping the current version.) |
POST /api/items/{id}/restore | Restore a previous version's content as a new edit. Body: { versionNo, version }. (Trash restore is POST /api/trash/{id} below.) |
POST /api/items/{id}/copy | Copy/publish an item to another library. |
POST /api/items/bulk-copy | Copy several items to one library in a batch: { ids, targetWorkspaceId } (max 100). Family members sync instead of duplicating. |
GET /api/items/{id}/lineage | The item's family tree: its source chain and every copy you can read, with per-copy freshness. |
GET /api/items/{id}/source-preview | The source's current content — review a diff before taking an update. |
POST /api/items/{id}/update-from-source | Take the source's latest. Body: { version } (409 if stale). |
POST /api/items/{id}/share | Create (or revoke) a public share link. |
POST /api/items/import · POST /api/items/import/github | Import files/.zip, or a GitHub repo (add token for a private one — used for that request only, never stored). |
GET /api/trash · POST /api/trash/{id} | List the Trash; restore an item. |
Tokens & account (session-only)
These require a signed-in browser session — a token can't call them.
| Method & path | Purpose |
|---|---|
GET /api/tokens | List your tokens (no secrets) + this month's usage. |
POST /api/tokens | Create a token: { name } → { token, … } (token shown once). |
DELETE /api/tokens/{id} | Revoke a token. |
GET /api/sessions · DELETE /api/sessions/{id} | List/sign-out active devices. |
POST /api/auth/2fa · POST /api/auth/totp | Enable/verify two-factor auth. |
POST /api/account/password · POST /api/account/delete | Change password; delete your account. |
Teams, companies & billing
Team/company management (/api/teams/*, /api/company/*, /api/invites/*), billing (/api/billing/*), and the admin console (/api/admin/*) back the in-app UI and enforce role checks server-side. They're documented functionally under Teams & Companies and Billing & Plans rather than as a public integration surface.
Errors
Standard HTTP status codes with a JSON { "error": "…" } body:
| Status | Meaning |
|---|---|
400 | Missing/invalid parameters. |
401 | Missing or invalid token / not signed in. |
403 | Authenticated but not allowed (role, or a network/IP restriction). |
404 | No such item or library. |
429 | Anti-abuse rate limit — slow down. |
409 | Edit conflict (someone else changed the item first). |
Quick recipes
List your libraries
curl -s https://www.aistoragedepot.com/api/workspaces \
-H "Authorization: Bearer YOUR_TOKEN"
Pull one library's items
curl -s "https://www.aistoragedepot.com/api/library?workspace=WORKSPACE_ID" \
-H "Authorization: Bearer YOUR_TOKEN"
Create a prompt
curl -s https://www.aistoragedepot.com/api/items \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"workspaceId":"WS_ID","typeId":"TYPE_ID","title":"Code review","body":"Review [language] code for [concern]."}'
Related: Connecting to your AI tools · Item Types · Security & Reliability