Screenpipe REST API reference at localhost:3030

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

Method	Endpoint	Description
POST	`/tags/{type}/{id}`	Add tags
DELETE	`/tags/{type}/{id}`	Remove tags

Retention & deletion

Method	Endpoint	Description
GET	`/retention/status`	Get retention status
POST	`/retention/configure`	Configure retention policy
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

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`
Scheduled task 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 scheduled task logs

For task-specific debugging, use the desktop app: Scheduled tasks → My tasks → open your scheduled task → view logs. Need help? join our Discord.

Get started

Recording and data

Scheduled tasks

Connect

Use cases

Personal and team knowledge

Workflow playbooks

Enterprise guides

Integrations

Reference

Deployment

Compare

Resources

Screenpipe REST API reference at localhost:3030

Endpoints

Search & content

Frames & elements

Meetings & speakers

Memories

Devices & health

Tags

Retention & deletion

Search example

Search parameters

Content type guide

Common API mistakes

Debugging

Enable verbose logging

Check health endpoint

Check scheduled task logs

​Endpoints

​Search & content

​Frames & elements

​Meetings & speakers

​Memories

​Devices & health

​Tags

​Retention & deletion

​Search example

​Search parameters

​Related context

​Content type guide

​Common API mistakes

​Debugging

​Enable verbose logging

​Check health endpoint

​Check scheduled task logs

Endpoints

Search & content

Frames & elements

Meetings & speakers

Memories

Devices & health

Tags

Retention & deletion

Search example

Search parameters

Related context

Content type guide

Common API mistakes

Debugging

Enable verbose logging

Check health endpoint

Check scheduled task logs