Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.screenpi.pe/llms.txt

Use this file to discover all available pages before exploring further.

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

parameteruse it when
qsearching for words or phrases
content_typenarrowing to ocr, audio, input, accessibility, or all
app_namefiltering to a desktop app
window_namefiltering to a window title
browser_urlfiltering to a website or URL pattern
speaker_namefinding what one person said
speaker_idsusing exact speaker IDs after cleanup
start_time / end_timeconstraining a meeting, work block, or incident
limit / offsetpaging through larger result sets

​
next steps