screenpipe API recipes

Copy-paste recipes for the most useful screenpipe API workflows: search, meetings, speakers, frames, memories, retention, archive, 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.

if API auth is enabled, add -H "Authorization: Bearer $SCREENPIPE_API_KEY" to requests. get the key with npx -y screenpipe@latest auth token or from settings -> privacy -> API security.

1. check that screenpipe is alive

curl http://localhost:3030/health

use this before debugging MCP, pipes, or chat. if it fails, the app is not serving the local API yet.

2. search everything recent

curl "http://localhost:3030/search?limit=20&content_type=all"

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 "http://localhost:3030/search?q=deployment&app_name=Slack&limit=20"
curl "http://localhost:3030/search?browser_url=github.com&limit=20"

use app_name for desktop app names and browser_url for web activity captured through browser metadata.

4. search a precise time window

curl "http://localhost:3030/search?start_time=2026-05-14T09:00:00Z&end_time=2026-05-14T12:00:00Z&limit=50"

time filters use ISO 8601 UTC. this is the safest way to debug “what happened during that call” or “what did I do before lunch?“

5. search meeting audio

curl "http://localhost:3030/search?q=budget&content_type=audio&limit=20"
curl "http://localhost:3030/search?content_type=audio&speaker_name=Sarah&limit=20"

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 "http://localhost:3030/activity-summary?start_time=2026-05-14T16:00:00Z&end_time=2026-05-14T18:00:00Z"

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

7. manage speakers

curl "http://localhost:3030/speakers/unnamed?limit=10"

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

curl -X POST http://localhost:3030/speakers/merge \
  -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 "http://localhost:3030/meetings?limit=20"
curl "http://localhost:3030/meetings/status"

curl -X POST http://localhost:3030/meetings/merge \
  -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 "http://localhost:3030/frames/123/text"
curl "http://localhost:3030/frames/123/context"
curl "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 "http://localhost:3030/elements?q=submit&limit=20"
curl "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 "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 "http://localhost:3030/memories?limit=20"

curl -X POST http://localhost:3030/memories \
  -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 "http://localhost:3030/retention/status"

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

retention keeps disk usage bounded. pair it with archive if you want old recordings moved out before deletion.

14. archive old data

curl "http://localhost:3030/archive/status"
curl -X POST http://localhost:3030/archive/run

archive is for moving older media to encrypted storage while keeping the local timeline searchable.

15. delete a time range

curl -X POST http://localhost:3030/data/delete-range \
  -H "Content-Type: application/json" \
  -d '{"start_time":"2026-05-14T09:00:00Z","end_time":"2026-05-14T10:00:00Z"}'

data deletion is permanent. export or archive anything you need 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	filtering to a website or URL pattern
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 pipes
• debug failed API calls in troubleshooting