Screenpipe API recipes

Copy-paste recipes for the most useful Screenpipe API workflows: search, meetings, speakers, frames, memories, retention, and safe data deletion.

Screenpipe runs a local API on localhost:3030. Use these recipes when you want useful answers fast, then open the API reference for every parameter and response shape.

Protected endpoints require API authentication. Retrieve the local key once per shell:

export SCREENPIPE_API_KEY="$(npx -y screenpipe@latest auth token)"

You can also reveal it in Settings → Privacy → API security. The examples below include the required bearer header. /health is the exception.

For scripts that call the API directly, add X-Screenpipe-Client: api as a fixed header. This identifies the request as an external API client; do not put an agent name, customer name, or prompt in this header:

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "X-Screenpipe-Client: api" \
  "http://localhost:3030/search?limit=20&start_time=24h+ago&end_time=now"

1. Check that Screenpipe is alive

curl http://localhost:3030/health

Use this before debugging MCP, scheduled tasks, or chat. If it fails, the app is not serving the local API yet.

2. Search the last 24 hours

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?limit=20&content_type=all&start_time=24h+ago&end_time=now"

content_type=all can return accessibility text, OCR fallback text, audio transcripts, input events, app names, window titles, and browser URLs.

3. Search one app or website

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?q=deployment&app_name=Slack&limit=20&start_time=24h+ago&end_time=now"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?browser_url=github.com&limit=20&start_time=24h+ago&end_time=now"

browser_url is matched against captured browser metadata; it is not a URL substring search. To find pages whose captured URL contains a domain or path, use q instead:

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?q=github.com&limit=20&start_time=24h+ago&end_time=now"

Use app_name for desktop app names and browser_url for exact or normalized URL filtering. URLs are also returned as metadata in matching results.

4. Search a precise time window

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?start_time=3h+ago&end_time=now&limit=50"

Time filters accept relative values such as 3h ago and now, or ISO 8601 UTC for an exact historical window. An explicit start and end is the safest way to debug “what happened during that call?”

5. Search meeting audio

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?q=budget&content_type=audio&limit=20&start_time=7d+ago&end_time=now"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/search?content_type=audio&speaker_name=Sarah&limit=20&start_time=7d+ago&end_time=now"

Speaker filters work best after you name or merge speakers in the meeting transcript sidebar or through the speaker APIs.

6. Summarize activity for an agent

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/activity-summary?start_time=2h+ago&end_time=now"

Use this when an AI agent needs a compact readout of a time range instead of raw search results.

7. Manage speakers

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  "http://localhost:3030/speakers/unnamed?limit=10"

curl -X POST http://localhost:3030/speakers/update \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "name": "Sarah Chen"}'

curl -X POST http://localhost:3030/speakers/merge \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"speaker_to_keep_id": 1, "speaker_to_merge_id": 2}'

Speaker cleanup improves meeting search, transcript readability, and calendar-assisted speaker identification.

8. List and update meetings

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/meetings?limit=20"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/meetings/status"

curl -X POST http://localhost:3030/meetings/merge \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meeting_ids": [12, 13]}'

Meetings are higher-level objects built from audio, transcript, timeline, and optional calendar context.

9. Fetch frame text and context

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/frames/123/text"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/frames/123/context"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/frames/123/metadata"

Use frame endpoints when you already have a frame_id from search and need the captured text, surrounding accessibility context, OCR fallback data, or metadata.

10. Search structured UI elements

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/elements?q=submit&limit=20"
curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/frames/123/elements"

Elements come from the accessibility tree. They are useful for finding buttons, links, fields, and UI labels directly, instead of relying on visual OCR.

11. Use read-only SQL

curl -X POST http://localhost:3030/raw_sql \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"select app_name, count(*) as n from frames group by app_name order by n desc limit 20"}'

/raw_sql only allows read-only queries such as select, with, and explain. Writes are rejected.

12. Work with memories

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/memories?limit=20"

curl -X POST http://localhost:3030/memories \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Important product insight from today", "source":"manual"}'

Memories are durable notes that AI workflows can search later.

13. Manage retention

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/retention/status"

curl -X POST http://localhost:3030/retention/configure \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "days": 30}'

Retention keeps disk usage bounded. Back up anything you need before cleanup because deleted ranges are not recoverable.

14. Delete a time range

curl -X POST http://localhost:3030/data/delete-range \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_time":"<START_UTC>","end_time":"<END_UTC>"}'

Replace both placeholders with reviewed ISO 8601 UTC timestamps. Data deletion is permanent; make a reviewed backup before deleting a range or device.

Filter cheat sheet

Parameter	Use it when
q	Searching for words or phrases
content_type	Narrowing to ocr, audio, input, accessibility, or all
app_name	Filtering to a desktop app
window_name	Filtering to a window title
browser_url	Exact or normalized filtering on captured browser metadata; use q for URL substring searches
speaker_name	Finding what one person said
speaker_ids	Using exact speaker IDs after cleanup
start_time / end_time	Constraining a meeting, work block, or incident
limit / offset	Paging through larger result sets

Next steps

• Connect AI tools with MCP server setup
• Build automations with scheduled tasks
• Debug failed API calls in troubleshooting