pipe permissions: scope API access for screenpipe pipes

Control which screenpipe API endpoints your pipes can access by allowlisting endpoints, restricting writes, and scoping permissions per automation.

overview

pipes can access the screenpipe API to read screen data, manage meetings, send notifications, and more. by default, pipes have full access to every endpoint — no restrictions.

if you want to limit what a pipe can do, add a permissions block to the YAML frontmatter in pipe.md. this is useful for:

• preventing accidents — a pipe that reads meetings shouldn’t be able to stop one
• least privilege — pipes from the store should only access what they need
• safety — deny destructive endpoints like /data/delete-range

quick start

---
schedule: every 30m
permissions: reader
---

Summarize my screen activity...

that’s it. this pipe can only read data — it can’t start/stop meetings, delete data, or run raw SQL.

presets

reader — safe read-only defaults

permissions: reader

allowed endpoints:

method	endpoint	description
GET	/search	query screen/audio data
GET	/activity-summary	app usage overview
GET	/elements	UI element search
GET	/frames/*	screenshots (if allow_frames: true)
GET	/meetings	list meetings
GET	/meetings/*	get meeting details
GET	/meetings/status	check if in meeting
POST	/notify	send notifications
GET	/speakers	list speakers
POST	/speakers/update	update speaker names
GET	/pipes/info	pipe metadata
GET	/health	health check
GET	/connections/*	connection credentials

everything else is denied.

writer — reader + write operations

permissions: writer

includes all reader endpoints, plus:

method	endpoint	description
POST	/meetings/start	start a manual meeting
POST	/meetings/stop	stop a manual meeting
PUT	/meetings/*	update meeting details
POST	/meetings/merge	merge meetings
POST	/memories	create memories
PUT	/memories/*	update memories
DELETE	/memories/*	delete memories

admin — full access (explicit)

permissions: admin

allows everything. functionally the same as no permissions block, but creates a token for logging/auditing.

custom rules

for fine-grained control, use allow and deny lists with Api(METHOD /path) patterns:

permissions:
  allow:
    - Api(GET /search)
    - Api(GET /meetings/*)
    - Api(POST /notify)
  deny:
    - Api(* /data/delete-*)

pattern syntax

pattern	matches
Api(GET /search)	exact: GET to /search
Api(GET /meetings/*)	glob: GET to /meetings/42, /meetings/status, etc.
Api(* /meetings/stop)	any method to /meetings/stop
Api(POST /notify)	exact: POST to /notify
Api(* /data/*)	any method to any /data/ subpath

* in the method position matches GET, POST, PUT, DELETE, etc. * in the path position matches any sequence of characters.

evaluation order

rules are evaluated in this order — first match wins:

1. deny — if the request matches any deny rule, it’s blocked (403)
2. allow — if the request matches any allow rule, it passes
3. default allowlist — if allow is empty and the pipe uses a preset with defaults (reader/writer), the default list is checked
4. reject — if nothing matched, the request is blocked

deny always wins over allow, just like firewall rules.

examples

deny specific endpoints (keep full access otherwise):

permissions:
  deny:
    - Api(* /meetings/stop)
    - Api(* /meetings/start)
    - Api(DELETE /meetings/*)
    - Api(* /data/delete-*)

allow only what you need (everything else denied):

permissions:
  allow:
    - Api(GET /search)
    - Api(POST /notify)

reader defaults + custom deny:

permissions:
  deny:
    - Api(GET /frames/*)

this uses the reader defaults but also blocks screenshot access.

data access rules

data filtering uses the same allow/deny lists with App(), Window(), and Content() rules:

---
schedule: every 1h
permissions:
  allow:
    - Api(GET /search)
    - App(Slack, Chrome)
    - Window(*meeting*)
    - Content(accessibility, audio)
  deny:
    - App(1Password, Signal)
    - Window(*incognito*, *bank*)
    - Content(input)
  time: "09:00-17:00"
  days: "Mon,Tue,Wed,Thu,Fri"
---

rule type	syntax	description
App(name)	App(Slack) or App(Slack, Chrome)	filter by app name (case-insensitive substring match)
Window(glob)	Window(*meeting*)	filter by window title (glob pattern)
Content(type)	Content(accessibility, audio)	filter content types: accessibility, ocr, audio, input
time	"09:00-17:00"	daily time window — supports midnight wrap ("22:00-06:00")
days	"Mon,Tue,Wed,Thu,Fri"	allowed days of the week

deny rules always win over allow rules. if no rules of a given type exist, everything is allowed.

how it works

when a pipe has any restrictions (permissions block, data filters, etc.):

1. screenpipe generates a unique token (sp_pipe_*) for the pipe session
2. the token is registered with the server middleware
3. every API request from the pipe includes the token in Authorization: Bearer sp_pipe_*
4. the middleware checks is_endpoint_allowed(method, path) before forwarding
5. the Pi extension also enforces rules client-side (blocks curl commands before they run)
6. when the pipe finishes, the token is cleaned up

pipes without any restrictions run without a token — full access, zero overhead.

common recipes

meeting-safe pipe

your pipe reads meeting data but should never interfere with active meetings:

---
schedule: every 1h
permissions:
  deny:
    - Api(* /meetings/start)
    - Api(* /meetings/stop)
    - Api(POST /meetings/merge)
    - Api(POST /meetings/bulk-delete)
    - Api(DELETE /meetings/*)
---

Summarize my meetings from the last hour...

read-only analytics pipe

---
schedule: daily
permissions:
  allow:
    - Api(GET /search)
    - App(Chrome, Arc, Firefox)
    - Content(accessibility)
---

Generate a daily browsing report...

work-hours-only pipe

---
schedule: every 30m
permissions:
  time: "09:00-17:00"
  days: "Mon,Tue,Wed,Thu,Fri"
---

Track my work activity...

full API access, but time and day restrictions limit when data is visible.

need help? ask in our discord