Docs / API, MCP & CLI Reference

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 & unmetered for individuals — the only throttle is an anti-abuse rate limit.

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/example libraries (Welcome, Curated) are for browsing in the app and are 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.

Local (stdio) — for desktop apps like Claude Desktop

{
  "mcpServers": {
    "aistoragedepot": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@aistoragedepot/mcp"],
      "env": { "AISTORAGEDEPOT_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	Every prompt, exposed as a native MCP prompt with its `[placeholders]` as fill-in arguments

Tools:

search_library — { "query": "keyword" }. Searches titles, bodies, tags, and categories across your own libraries. Returns matches with their aisd://item/<id> URIs. (Needs ≥ 2 characters.)
get_item — { "id": "<id or aisd://item/<id>>" }. Returns the full body of one item.

Server details: server name aistoragedepot, protocol version 2024-11-05. Deactivated items and the example libraries are excluded. Individuals are unmetered; the anti-abuse limit returns JSON-RPC error -32003 with HTTP 429. A missing/invalid token returns -32001 with HTTP 401.

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.

`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.

Why `--types=skill` is the default

Prompts already come across live over MCP as slash commands. If you also pull them, they register a second time — you'd see each prompt twice in your menu (a (user) frozen copy and a live (MCP) copy). Skills, by contrast, are documents the agent reads over MCP — they only become a typed /command when you pull them. So the safe default is: let MCP serve prompts, and pull your skills. Re-run pull any time to refresh the local copies; it only touches AIStorageDepot files.

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.

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 (no Welcome/Curated).
`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.
`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.
`GET/PATCH/DELETE /api/items/{id}`	Read, edit, or delete one item.
`GET /api/items/{id}/versions` · `GET .../versions/{v}`	Version history, and one specific version.
`POST /api/items/{id}/restore`	Restore from Trash.
`POST /api/items/{id}/copy`	Copy/publish an item to another library.
`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 public GitHub repo.
`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]."}'