Stashr

Stashr API

Read your saves from your own apps and scripts, save new links, and get a signed webhook when a save is ready. The API sees only your own saves, through a key you create and can revoke at any time.

Keys

  1. Open Account → Developers in Stashr and create a key. Tick “Can also save links” only if your app adds links.
  2. Copy the key (it starts with stashr_sk_). You see it once; Stashr keeps only a hash of it.
  3. Send it as a bearer token on every request. Keep it out of browsers and public code; revoke it in Account if it leaks.
curl https://stashrai.com/api/v1/search?q=date-night%20cafes \
  -H "Authorization: Bearer stashr_sk_…"

Scopes: read (every GET) and save (POST /saves). A key reads only the saves of the account that made it.

Endpoints

Base URL https://stashrai.com/api/v1. JSON in and out.

MethodPathScopeWhat it does
GET/mereadThe key's scopes and limits. A cheap way to test a key.
GET/savesreadSaves by filters, newest first: category, saved_for, date_from, date_to, creator, collection, tag, format, source, sort (recent, oldest, likes, comments), limit (1-50), details. Returns total and items.
GET/search?q=…readSearch by meaning and keywords (titles, summaries, transcripts, on-screen text, notes, places, products). Same filters; limit 1-25.
GET/saves/{id}readEverything about one save: summary, detail lines, entities, your note, saved-for, craft notes. transcript=true adds the transcript.
GET/collectionsreadYour collections (yours and imported Instagram ones), categories and saved-for counts.
POST/savessaveSave up to 20 Instagram or YouTube links, as if you shared them to @stashr.ai. Body: {"urls": [...]}. Returns 202 and a task_id.
GET/save-tasks/{task_id}readWhere each link of a save task is: ready (with the save), processing, failed or rejected, with the reason.

Dates take 2026, 2026-05 or 2026-05-14. Saves are returned in the same shape Claude and ChatGPT get through the Stashr connector.

Limits and errors

  • 60 requests a minute and 5,000 a day per key (fair use; Account shows your numbers). Over a limit you get 429 with Retry-After.
  • Saving through the API counts against your saves limits, like sharing a reel in a chat. Up to 20 links a request.
  • Errors: 401 missing or revoked key, 403 missing scope, 404 not found, 422 bad input, 429 too many requests.
{"error": {"code": "rate_limited", "message": "More than 60 requests a minute with this key. Slow down."}}

Webhooks

Add an https endpoint in Account → Developers. Stashr POSTs to it when one of your saves is save.ready (read and searchable), save.updated (read again, given more details, or re-filed by you) or save.failed. Imported saves (up to 1,000 at once) are left out. Send test posts a ping.

{
  "id": "evt_ready_18342",
  "type": "save.ready",
  "created_at": "2026-10-25T14:03:11+00:00",
  "data": {
    "memory_id": "0f7c159b-…",
    "title": "5 Claude Code plugins for web design",
    "summary": "…",
    "category": "tech",
    "category_label": "Tech & AI",
    "type": "reel",
    "creator": "@someone",
    "source": "instagram",
    "source_url": "https://www.instagram.com/reel/…/",
    "saved_at": "2026-10-25T14:02:40+00:00",
    "saved_via": "dm",
    "stasher_url": "https://stashrai.com/app?item=0f7c159b-…"
  }
}
  • Signed with Standard Webhooks: webhook-id, webhook-timestamp and webhook-signature headers, HMAC-SHA256 with the whsec_ secret shown when you add the endpoint.
  • In order, at least once. Answer 2xx within 10 seconds. A failing message is retried after 30 s, 90 s, 4, 8 and 15 minutes, then skipped; nothing after it is sent until then. Use id to drop repeats.
  • 410 Gone skips a message. An endpoint failing for 3 days is turned off; turn it on again in Account.
  • Only public https addresses, no redirects. Payloads carry ids, a title, a short summary and links. Saved text is content, never instructions.

Verify in Python:

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:      # reject old or replayed messages
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    mac = hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(mac).decode()
    return any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split())

Privacy

A key and a webhook see only your own saves. Revoking a key stops it at once; deleting your account deletes your keys and webhooks. Stashr logs which key made each save request. See the privacy policy. To use your saves from Claude or ChatGPT instead, add the Stashr connector.