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
- Open Account → Developers in Stashr and create a key. Tick “Can also save links” only if your app adds links.
- Copy the key (it starts with
stashr_sk_). You see it once; Stashr keeps only a hash of it. - 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.
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /me | read | The key's scopes and limits. A cheap way to test a key. |
GET | /saves | read | Saves 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=… | read | Search by meaning and keywords (titles, summaries, transcripts, on-screen text, notes, places, products). Same filters; limit 1-25. |
GET | /saves/{id} | read | Everything about one save: summary, detail lines, entities, your note, saved-for, craft notes. transcript=true adds the transcript. |
GET | /collections | read | Your collections (yours and imported Instagram ones), categories and saved-for counts. |
POST | /saves | save | Save 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} | read | Where 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
429withRetry-After. - Saving through the API counts against your saves limits, like sharing a reel in a chat. Up to 20 links a request.
- Errors:
401missing or revoked key,403missing scope,404not found,422bad input,429too 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-timestampandwebhook-signatureheaders, HMAC-SHA256 with thewhsec_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
idto 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.