Lens reference

Keys

Key	Where it lives	What it can do
lens_pk_…	in your page, visible to anyone	send browser events for that project
lens_sk_…	your server only	send events, and mark a person verified

Rotating keys mints new ones and retires the old pair.

Creating a project, renaming or deleting one, rotating its keys, setting its alerts and declaring a funnel are workspace administration: a member reads them and gets admin_required on the write. See Roles and permissions.

Ingest

POST /v1/ingest/{public_key}     browser; no session
POST /v1/events                  server; Authorization: Bearer lens_sk_…

An unknown public key is a 404. A project with ingest switched off answers 202 and stores nothing, so a page keeps working while you stop collecting.

Retries are safe: the ledger that de-duplicates them is keyed independently of the event’s own timestamp, so a retry whose clock shifted still counts once.

Browser ingest is the one place in the suite that allows any origin, with no credentials, chosen by an explicit path list. The SDK posts text/plain so sendBeacon never triggers a preflight.

Reads

All workspace-scoped; a project id from another workspace is a 404, not a 403.

/v1/projects                 list, create
/v1/projects/{id}            read, update, delete
/v1/projects/{id}/keys:rotate
/v1/projects/{id}/events     the raw feed
/v1/projects/{id}/trends     per day
/v1/projects/{id}/retention  came-back-by-day
/v1/projects/{id}/funnels    declare, list, run, delete
/v1/projects/{id}/segment    one slice
/v1/projects/{id}/breakdown?by=…
/v1/projects/{id}/properties the keys you have actually sent
/v1/projects/{id}/errors     groups; /{group}/resolve, /{group}/issue
/v1/projects/{id}/persons/{person}          DELETE erases one person; /export
/v1/projects/{id}/alerts
/v1/projects/{id}/export
/v1/projects/{id}/test-event
/v1/previews/{preview}       what happened in a preview environment
/v1/usage                    this workspace, this month

breakdown by=

A closed set: name, path, referrer_host, country, device_class, source, person — or p.<key> for a property you sent, or c.<key> for a context key. Closed on purpose: the value names a column.

Narrowing

?person= and ?p.<key>= (at most five at once) apply to events, segment and breakdown. errors accepts neither yet.

dst lens

Every command below was taken from --help, not from memory.

dst lens projects                                  # list
dst lens project create "My app"                   # prints the install snippet
dst lens project show <project-id>
dst lens project update <project-id>               # name, retention, identity mode, kill switch
dst lens project rotate-keys <project-id>          # the old pair stops working immediately
dst lens project test-event <project-id>           # prove the pipe without a visitor
dst lens project delete-person <project-id> <person-id>
dst lens project export <project-id> --file out.ndjson   # --person <id> for one person; never overwrites
dst lens project delete <project-id>

dst lens events <project-id> --limit 50
dst lens events <project-id> --person u_123
dst lens events <project-id> --property plan=pro
dst lens trends <project-id> --days 30
dst lens retention <project-id> --days 7
dst lens breakdown <project-id> path --limit 10 --event pageview
dst lens segment <project-id> plan pro
dst lens usage

dst lens errors list <project-id>
dst lens errors show <project-id> <group-id>
dst lens errors resolve <project-id> <group-id>
dst lens errors issue <project-id> <group-id>      # opens it in Space
dst lens errors alerts <project-id>
dst lens errors set-alerts <project-id>

dst lens funnel declare <project-id> <name> <step> <step> [step...]
dst lens funnel list <project-id>
dst lens funnel run <project-id> <funnel-id> --days 7
dst lens funnel delete <project-id> <funnel-id>

dst lens preview <preview-id>

The dimension for breakdown and the key/value for segment are POSITIONAL, not flags.

MCP

lens_list_projects, lens_get_project, lens_create_project, lens_update_project, lens_delete_project, lens_rotate_keys, lens_list_events, lens_get_trends, lens_get_retention, lens_get_breakdown, lens_get_segment, lens_list_errors, lens_get_error, lens_resolve_error, lens_file_issue, lens_list_funnels, lens_declare_funnel, lens_run_funnel, lens_delete_funnel, lens_get_alerts, lens_set_alerts, lens_get_usage, lens_delete_person, lens_send_test_event, lens_get_preview_insights.

The assistant

On the project page, and at POST /v1/chat. It holds no history between turns — the client replays the conversation — and pauses for your approval before anything with consequences: setting alerts, resolving an error, deleting a person, deleting a project.

file_issue is refused there whatever you answer. Filing into Space needs your own credentials, and a chat session carries a cookie rather than a token that Space would accept; a service credential would let anyone with a Lens session write into a workspace they cannot see. Use the UI, dst lens errors issue, or the MCP tool, which all carry your own authority.