REST API Overview

Introduction to the Screenpipe REST API

The Screenpipe REST API provides programmatic access to all captured screen and audio data. The API runs locally on your machine and follows REST conventions with JSON request/response bodies.

Base URL

By default, the Screenpipe server runs on:

http://localhost:3030

You can customize the port using the --port flag when starting Screenpipe:

screenpipe --port 3035

Authentication

The local API does not require authentication by default. All requests are made to localhost and are only accessible from your machine.

If you expose the API to a network, ensure you implement proper security measures as the API provides access to all your captured data.

Response Format

All API responses follow a consistent JSON structure:

Successful Response

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150
  }
}

Error Response

{
  "error": "Error message describing what went wrong",
  "statusCode": 400
}

Common HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn’t exist
500	Internal Server Error

Content Types

Screenpipe captures and indexes multiple types of content:

contentType · string · default: "all"

Filter results by content type:

• all - OCR + Audio + Accessibility text
• ocr - Screen text from screenshots
• audio - Transcribed speech
• input - User actions (clicks, keystrokes, clipboard)
• accessibility - Accessibility tree text

Pagination

Most list endpoints support pagination using standard parameters:

limit · number · default: "20"

Maximum number of results to return (max: 100)

offset · number · default: "0"

Number of results to skip for pagination

Example:

# Get first 20 results
curl "http://localhost:3030/search?limit=20&offset=0"

# Get next 20 results
curl "http://localhost:3030/search?limit=20&offset=20"

Time Filtering

Filter results by time range using ISO 8601 timestamps:

start_time · string

Filter results after this timestamp (ISO 8601 format)

end_time · string

Filter results before this timestamp (ISO 8601 format)

Example:

const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
const now = new Date().toISOString();

const response = await fetch(
  `http://localhost:3030/search?start_time=${fiveMinutesAgo}&end_time=${now}`
);

Core Endpoints

Health Check

GET /health

Returns server health status and capture statistics.

Search

GET /search

Full-text search across all captured content. See Search API for details.

Keyword Search

GET /search/keyword

Search for specific keywords with text positions and bounding boxes.

Frames

GET /frames/:frame_id

Retrieve screenshot frames and OCR data.

Audio Devices

GET /audio/list

List available audio input/output devices.

Monitors

GET /vision/list

List available displays and their configurations.

Rate Limiting

The local API does not enforce rate limits. However, complex queries on large datasets may take time to process.

CORS

CORS is enabled by default to allow web-based applications to access the API from localhost.

Next Steps

Search API

Query your captured data

JavaScript SDK

Use the official Node.js SDK

Streaming

Real-time data streams

Frames API

Access screenshot frames