> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

{/* https://screenpi.pe */}

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.

<Note>
  for copy-paste workflows, start with [API recipes](/api-recipes). for the full interactive API reference with request/response schemas, see the API reference tab.
</Note>

<Warning>
  the local search endpoint is `/search`, not `/api/search`.

  ```bash theme={null}
  curl "http://localhost:3030/search?limit=5"
  ```
</Warning>

## 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

```bash theme={null}
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:

```bash theme={null}
curl "http://localhost:3030/search?tags=person:ada&include_related=true&limit=5"
```

```json theme={null}
{
  "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:**

```bash theme={null}
SCREENPIPE_LOG=debug npx -y screenpipe@latest
```

**Windows (PowerShell):**

```powershell theme={null}
$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:

```bash theme={null}
SCREENPIPE_LOG=screenpipe=debug,vision=debug npx -y screenpipe@latest
```

### check health endpoint

verify screenpipe is running properly:

```bash theme={null}
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](https://discord.gg/screenpipe).