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 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
| method | endpoint | description |
|---|
| GET | /search | search screen & audio content |
| GET | /health | server health check |
| GET | /audio/list | list audio devices |
| GET | /vision/list | list monitors |
| GET | /frames/{id} | get frame data |
| GET | /frames/{id}/ocr | get frame OCR fallback text and bounds |
| POST | /tags/{type}/{id} | add tags |
| DELETE | /tags/{type}/{id} | remove tags |
| POST | /raw_sql | execute raw SQL |
| POST | /add | add content to database |
| GET | /search/keyword | keyword search |
| POST | /audio/start | start audio recording |
| POST | /audio/stop | stop audio recording |
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 |
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 |
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 screenpipe
$env:SCREENPIPE_LOG = "debug"
screenpipe
debug — detailed diagnostic informationinfo — general informational messages (default)warn — warnings only (less verbose)
you can also target specific modules for debugging:
SCREENPIPE_LOG=screenpipe=debug,vision=debug screenpipe
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.