screenpipe API recipes

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.

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 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"

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

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. pair it with archive if you want old recordings moved out before deletion.

14. archive old data

curl -H "Authorization: Bearer $SCREENPIPE_API_KEY" "http://localhost:3030/archive/status"
curl -X POST http://localhost:3030/archive/run \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY"

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 "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; 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

get started

pipes

connect

use cases

integrations

reference

deployment

compare

resources

1. check that screenpipe is alive

2. search the last 24 hours

3. search one app or website

4. search a precise time window

5. search meeting audio

6. summarize activity for an agent

7. manage speakers

8. list and update meetings

9. fetch frame text and context

10. search structured UI elements

11. use read-only SQL

12. work with memories

13. manage retention

14. archive old data

15. delete a time range

filter cheat sheet

next steps

​1. check that screenpipe is alive

​2. search the last 24 hours

​3. search one app or website

​4. search a precise time window

​5. search meeting audio

​6. summarize activity for an agent

​7. manage speakers

​8. list and update meetings

​9. fetch frame text and context

​10. search structured UI elements

​11. use read-only SQL

​12. work with memories

​13. manage retention

​14. archive old data

​15. delete a time range

​filter cheat sheet

​next steps

1. check that screenpipe is alive

2. search the last 24 hours

3. search one app or website

4. search a precise time window

5. search meeting audio

6. summarize activity for an agent

7. manage speakers

8. list and update meetings

9. fetch frame text and context

10. search structured UI elements

11. use read-only SQL

12. work with memories

13. manage retention

14. archive old data

15. delete a time range

filter cheat sheet

next steps