screenpipe REST API reference at localhost:3030

Complete REST API reference for screenpipe at localhost:3030 — search screen history, query frames, audio transcripts, tags, health, and more endpoints.

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

method	endpoint	description
GET	/search	search screen & audio content
GET	/search/keyword	keyword search
GET	/activity-summary	compact activity readout for a time range
POST	/raw_sql	execute read-only SQL
POST	/add	add content to database

frames & elements

method	endpoint	description
GET	/frames/{id}	get frame data
GET	/frames/{id}/text	get frame text and bounds
GET	/frames/{id}/ocr	get frame OCR fallback text and bounds
GET	/frames/{id}/context	get surrounding accessibility context
GET	/frames/{id}/metadata	get frame metadata
GET	/frames/{id}/elements	get UI elements for a frame
GET	/elements	search structured UI elements

meetings & speakers

method	endpoint	description
GET	/meetings	list meetings
GET	/meetings/status	meeting detection status
POST	/meetings/merge	merge meetings
GET	/speakers/unnamed	list unnamed speakers
POST	/speakers/update	rename a speaker
POST	/speakers/merge	merge speakers

memories

method	endpoint	description
GET	/memories	list memories
POST	/memories	create a memory

devices & health

method	endpoint	description
GET	/health	server health check
GET	/audio/list	list audio devices
GET	/vision/list	list monitors
POST	/audio/start	start audio recording
POST	/audio/stop	stop audio recording

tags

method	endpoint	description
POST	/tags/{type}/{id}	add tags
DELETE	/tags/{type}/{id}	remove tags

retention, archive & deletion

method	endpoint	description
GET	/retention/status	get retention status
POST	/retention/configure	configure retention policy
GET	/archive/status	get archive status
POST	/archive/run	run archive now
POST	/data/delete-range	permanently delete data in a time range

search example

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

search parameters

param	type	description
q	string	search query
limit	int	max results
offset	int	pagination offset
content_type	string	ocr, audio, input, accessibility, all
start_time	ISO 8601	filter start
end_time	ISO 8601	filter end
app_name	string	filter by app
window_name	string	filter by window title
browser_url	string	filter by browser URL
min_length	int	minimum text length
max_length	int	maximum text length
tags	string	comma-separated; return only items carrying all of these tags, e.g. tags=person:ada,project:atlas
include_related	bool	with tags, attach a related block of co-occurring tags grouped by namespace

related context

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 type	use it for
all	first debugging pass; searches across available screen and audio data
accessibility	app text exposed by macOS/Windows accessibility APIs; best for most screen text
ocr	fallback pixel text when accessibility data is missing or incomplete
audio	transcripts and meeting/call content
input	keyboard/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

symptom	cause	fix
404 on /api/search	wrong path	use /search
empty response after startup	capture has not processed yet	wait 1-2 minutes and retry
no result for a specific window	stored title differs	search broad, inspect window_name, then filter
OCR result missing app text	app exposes text through accessibility instead	try content_type=accessibility or all
pipe gets old data	schedule or time range too narrow	widen 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.