Skip to main content

​
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

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

allowed endpoints: everything else is denied.

​
writer — reader + write operations

includes all reader endpoints, plus:

​
admin — full access (explicit)

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:

​
pattern syntax

* 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):
allow only what you need (everything else denied):
reader defaults + custom deny:
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:
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:

​
read-only analytics pipe

​
work-hours-only pipe

full API access, but time and day restrictions limit when data is visible. need help? ask in our discord