Skip to main content
this is the REST API reference for localhost:3030; for CLI commands see the guides. screenpipe serves a REST API on localhost:3030. use this to integrate with any tool or build custom automations.
for copy-paste workflows, start with API recipes. for the full interactive API reference with request/response schemas, see the API reference tab.
the local search endpoint is /search, not /api/search.
curl "http://localhost:3030/search?limit=5"

​
endpoints

​
search & content

methodendpointdescription
GET/searchsearch screen & audio content
GET/search/keywordkeyword search
GET/activity-summarycompact activity readout for a time range
POST/raw_sqlexecute read-only SQL
POST/addadd content to database

​
frames & elements

methodendpointdescription
GET/frames/{id}get frame data
GET/frames/{id}/textget frame text and bounds
GET/frames/{id}/ocrget frame OCR fallback text and bounds
GET/frames/{id}/contextget surrounding accessibility context
GET/frames/{id}/metadataget frame metadata
GET/frames/{id}/elementsget UI elements for a frame
GET/elementssearch structured UI elements

​
meetings & speakers

methodendpointdescription
GET/meetingslist meetings
GET/meetings/statusmeeting detection status
POST/meetings/mergemerge meetings
GET/speakers/unnamedlist unnamed speakers
POST/speakers/updaterename a speaker
POST/speakers/mergemerge speakers

​
memories

methodendpointdescription
GET/memorieslist memories
POST/memoriescreate a memory

​
devices & health

methodendpointdescription
GET/healthserver health check
GET/audio/listlist audio devices
GET/vision/listlist monitors
POST/audio/startstart audio recording
POST/audio/stopstop audio recording

​
tags

methodendpointdescription
POST/tags/{type}/{id}add tags
DELETE/tags/{type}/{id}remove tags

​
retention, archive & deletion

methodendpointdescription
GET/retention/statusget retention status
POST/retention/configureconfigure retention policy
GET/archive/statusget archive status
POST/archive/runrun archive now
POST/data/delete-rangepermanently delete data in a time range

​
search example

curl "http://localhost:3030/search?q=meeting&limit=10&content_type=all"

​
search parameters

paramtypedescription
qstringsearch query
limitintmax results
offsetintpagination offset
content_typestringocr, audio, input, accessibility, all
start_timeISO 8601filter start
end_timeISO 8601filter end
app_namestringfilter by app
window_namestringfilter by window title
browser_urlstringfilter by browser URL
min_lengthintminimum text length
max_lengthintmaximum text length
tagsstringcomma-separated; return only items carrying all of these tags, e.g. tags=person:ada,project:atlas
include_relatedboolwith tags, attach a related block of co-occurring tags grouped by namespace
pass include_related=true alongside a tags filter to get the tags that co-occur with the ones you asked for — the people, projects, and workflows that show up in the same frames, calls, and memories — in a single call instead of several follow-up queries: 
curl "http://localhost:3030/search?tags=person:ada&include_related=true&limit=5"

{
  "data": [ "...frames, audio, and memories..." ],
  "pagination": { "limit": 5, "offset": 0, "total": 42 },
  "related": {
    "people": ["connor", "drew"],
    "projects": ["atlas", "atlas-finance"],
    "workflows": ["planning"]
  }
}
namespaces are pluralized from the tag prefix (person: → people, project: → projects); values are ordered most-frequent first. omit tags and the block is skipped.

​
content type guide

content typeuse it for
allfirst debugging pass; searches across available screen and audio data
accessibilityapp text exposed by macOS/Windows accessibility APIs; best for most screen text
ocrfallback pixel text when accessibility data is missing or incomplete
audiotranscripts and meeting/call content
inputkeyboard/input-related records where available
start with content_type=all. add app_name, window_name, or time filters only after you confirm broad search returns data.

​
common API mistakes

symptomcausefix
404 on /api/searchwrong pathuse /search
empty response after startupcapture has not processed yetwait 1-2 minutes and retry
no result for a specific windowstored title differssearch broad, inspect window_name, then filter
OCR result missing app textapp exposes text through accessibility insteadtry content_type=accessibility or all
pipe gets old dataschedule or time range too narrowwiden start_time/end_time or run manually

​
debugging

​
enable verbose logging

to troubleshoot issues, enable debug logging by setting the SCREENPIPE_LOG environment variable before starting screenpipe: macOS/Linux: 
SCREENPIPE_LOG=debug npx -y screenpipe@latest
Windows (PowerShell): 
$env:SCREENPIPE_LOG = "debug"
npx -y screenpipe@latest
logs will print to the terminal. common log levels:
  • debug — detailed diagnostic information
  • info — general informational messages (default)
  • warn — warnings only (less verbose)
you can also target specific modules for debugging: 
SCREENPIPE_LOG=screenpipe=debug,vision=debug npx -y screenpipe@latest

​
check health endpoint

verify screenpipe is running properly: 
curl http://localhost:3030/health

​
check pipe logs

for pipe-specific debugging, use the desktop app: settings → pipes → click your pipe → view logs. need help? join our discord.