Projects
Create a project, issue a DSN, set retention and ingest caps, with UI steps and copyable API curls.
One instrumented app or service under your workspace. Each project owns DSN keys, retention, ingest cap, releases, alerts, and webhooks.
What is a project?
One instrumented app or service. It owns DSN keys, retention, an ingest cap, releases, and webhooks.
Workspace hierarchy
Workspace (org)
└── Project
├── DSN keys (create / rotate / revoke)
├── Issues + events
├── Releases + JS/TS artifacts
└── WebhooksDashboard tenancy is RLS on org_id. Ingest tenancy is the DSN → project_id lookup. Switching projects changes :projectId in /p/:projectId/….
How do I create a project?
UI:
- Open workspace home:
/ - As Owner or Admin, enter a name and create the project
- Open the project (defaults to Issues)
- Go to Settings → SDK connection and create a key
- Point the official Sentry SDK at that DSN (change
dsnonly)
Members can open projects and triage; they cannot create projects or manage keys.
Session required. Login first (Settings):
Create a project
command
curl -sS -b cookies.txt -X POST \
"http://localhost:8080/api/v1/projects" \
-H "Content-Type: application/json" \
-d '{"name":"Acme Web"}'Expected
HTTP/1.1 201 Created
{ "id": "<project-uuid>", "org_id": "<org-uuid>", "name": "Acme Web", "slug": "acme-web-a1b2c3d4", "retention_days": 30, "ingest_cap_per_hour": 5000 }Empty name → 400. Member session → 403.
What is a DSN?
The ingest URL for this project. Create, rotate, or revoke keys at /p/:projectId/settings/dsn.
| Action | Effect |
|---|---|
| Create | New public/secret pair. The secret is shown once, so copy it |
| Rotate | Revokes active keys and issues a new pair; update SDKs |
| Revoke | Key stops ingesting; requests return 403 dsn_revoked |
http://{public_key}@localhost:8080/{project_id}Production uses https:// and your EPURE_PUBLIC_URL host.
Create a DSN key
command
curl -sS -b cookies.txt -X POST \
"http://localhost:8080/api/v1/projects/${PROJECT_ID}/dsn-keys" \
-H "Content-Type: application/json" \
-d '{"label":"browser"}'Expected
HTTP/1.1 201 Created
{ "id": "<key-uuid>", "public_key": "a1b2…", "secret_key": "<shown once>", "label": "browser" }Point the SDK:
Sentry.init({
dsn: "http://YOUR_PUBLIC_KEY@localhost:8080/YOUR_PROJECT_ID",
environment: "local",
tracesSampleRate: 0,
});Revoke: POST /api/v1/dsn-keys/{id}/revoke → { "revoked": true }. Then ingest returns 403. A DSN cannot read issues; that needs a session.
Project settings
Route: /p/:projectId/settings
| Field | Notes |
|---|---|
| Display name | Shown in the shell and project list |
| Retention | Raw events: 14, 30 (default), or 90 days. Issue aggregates remain after TTL |
| Ingest cap | Hard rate limit per hour (default 5000). Excess events are dropped (403 ingest_cap_exceeded) |
| Delete project | Owner only |
Set retention and ingest cap
command
curl -sS -b cookies.txt -X PATCH \
"http://localhost:8080/api/v1/projects/${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{"retention_days":14,"ingest_cap_per_hour":2000}'Expected
{ "id": "<project-uuid>", "retention_days": 14, "ingest_cap_per_hour": 2000, "name": "Acme Web" }retention_days must be 14, 30, or 90. Anything else → 400.
Environments vs projects
Environment is an event tag, not a separate project. Filter on the top strip so staging crashes stay out of production triage.
Common values: production, staging, local. Retention applies per project, not per environment.
Why 403 on ingest after rotate?
Rotate revokes active keys and issues a new pair, so update dsn in the SDK. Old public keys return 403 dsn_revoked. Create a key instead if you only needed a new label. Then confirm with Verify.
Why can I not delete a project?
Delete is Owner-only; Members and Admins cannot. Sign in as Owner or transfer ownership from /team. Members can still triage issues on that project. Empty name on create is 400, and a Member create is 403.
How does retention work?
Raw events live in monthly partitions events_YYYY_MM. Choose 14, 30 (default), or 90 days; other values return 400. TTL drops old partitions and issue aggregates remain. Patch via project settings or PATCH /api/v1/projects/{id}.