/screenpipe-api

name: screenpipe-api
description: Query the user's local and synced-device Screenpipe data via the REST API at localhost:3030. Use for screen activity, meetings, apps, productivity, other-device or cross-device history, media export, retranscription, or connected services.

Screenpipe API

Local REST API at `http://localhost:3030`. Full reference (60+ endpoints): https://docs.screenpi.pe/llms-full.txt

Authentication

**ALL requests require authentication.** Add the auth header to every curl call:

curl -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  -H "X-Screenpipe-Client: api" \
  -H "X-Screenpipe-Agent: unknown" \
  "http://localhost:3030/..."

The fixed `X-Screenpipe-Client: api` value attributes a successful, nonempty external retrieval to the API surface. Never put an agent name, customer name, project, prompt, or other dynamic value in this header. Include both attribution headers above on REST retrievals. The installer sets `X-Screenpipe-Agent` to a fixed app identifier; preserve that value. If this is an unconfigured reference, leave it as `unknown`. Never substitute a project, user, model, prompt, or other dynamic identifier.

The `$SCREENPIPE_LOCAL_API_KEY` env var is already set in your environment. Without it you get 403. The only exception is `/health` (no auth needed).

Context Window Protection

API responses can be large. Always write curl output to a file first (`curl ... -o /tmp/sp_result.json`), check size (`wc -c /tmp/sp_result.json`), and if over 5KB read only the first 50-100 lines. Extract what you need with `jq`. NEVER dump full large responses into context.

For the list endpoints (`/search`, `/elements`, `/frames/{id}/elements`) you can also cut tokens at the source: add `&format=csv` (or `tsv`) to get a columnar table that writes each column name once instead of repeating keys per row, and `&fields=a,b,c` to return only the columns you need (dotted paths like `content.text`). On a list of UI elements that is roughly a 70% token cut versus JSON. For the element endpoints specifically, `&format=outline` (alias `tree`) goes further still — a deduped, indented tree of just the text-bearing nodes (~91% fewer tokens, measured) — and is the best default for reading UI structure. Use `&format=automation` for automation planning: it retains interactive controls, state, bounds, allowed actions, short response-local refs, and best-effort stable keys. Text-heavy `ocr`/`audio` barely benefit from any reshaping (the text blob dominates), so reach for `fields` + `max_content_length` there. With no `format`/`fields` the response is unchanged JSON.

---

1. Search — `GET /search`

curl -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  -H "X-Screenpipe-Client: api" \
  -H "X-Screenpipe-Agent: unknown" \
  "http://localhost:3030/search?q=QUERY&content_type=all&limit=10&start_time=1h%20ago"

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `q` | string | No | Keywords. Do NOT use for audio searches — transcriptions are noisy, q filters too aggressively. | | `content_type` | string | No | `all` (default), `accessibility`, `audio`, `input`, `ocr`, `memory`, `parsed`. Use `parsed` for compact app-specific messages, emails, tasks, documents, and code review. Parsed capture is experimental, may be empty when disabled/unsupported, and is not included in `all`. Screen text is primarily captured via the OS accessibility tree (`accessibility`); OCR is a fallback for apps without accessibility support. | | `limit` | integer | No | Max 1-20. Default: 10 | | `offset` | integer | No | Pagination. Default: 0 | | `start_time` | ISO 8601, relative, or local calendar | **Yes** | Accepts `2024-01-15T10:00:00Z`, `16h ago`, `today`, `yesterday`, or `YYYY-MM-DD` | | `end_time` | Same as `start_time` | No | Defaults to `now` | | `app_name` | string | No | e.g. "Google Chrome", "Slack", "zoom.us" | | `window_name` | string | No | Window title substring | | `frame_id` | integer | No | With `content_type=parsed`, return parsed data attached to one frame. | | `actor_id` | integer | No | With `content_type=parsed`, filter by a resolved actor identity. | | `speaker_name` | string | No | Filter audio by speaker (case-insensitive partial) | | `focused` | boolean | No | Only focused windows | | `tags` | string | No | Comma-separated; return only items carrying ALL of them (e.g. `person:ada,project:atlas`). Works for screen/audio and, with `content_type=memory`, memories. See Tags below. | | `include_related` | boolean | No | With `tags`, also return a `related` map of co-occurring tags (people/projects/workflows seen alongside yours), most-frequent first. One call for the surrounding context instead of several. See Tags below. | | `max_content_length` | integer | No | Truncate each result's text (middle-truncation) | | `format` | string | No | `json` (default), `csv`, `tsv`/`table`, or `outline`/`tree` (element endpoints only). CSV/TSV return a columnar table (column names written once) instead of one JSON object per row. `outline` returns a deduped indented text tree of the text-bearing UI nodes — the cheapest read for "what's on screen?" (~91% fewer tokens). CSV is lossless; TSV collapses newlines (worse for long `ocr` text). | | `fields` | string | No | Comma-separated column allowlist of dotted paths, e.g. `type,content.app_name,content.text`. Returns only those columns (handy for dropping the repeated absolute `content.file_path`). Works for `json` too (sparse objects). |

Progressive Disclosure

Don't jump to heavy `/search` calls. Escalate:

| Step | Endpoint | When | |------|----------|------| | 0 | `GET /memories?q=...` | **Always query first/in parallel** — highest signal, lowest cost | | 1 | `GET /activity-summary?start_time=...&end_time=...` | Broad questions ("what was I doing?", "which apps?") | | 2 | `GET /search?...` | Need specific content | | 3 | `GET /elements?...` or