Projects

CRUD endpoints for managing projects — create, list, get, update, and delete projects within teams.

Create, list, get, update, and delete projects. Projects group related apps across platforms (e.g., a "MyApp" project containing iOS, Android, and web apps).

GET /v1/projects

List all projects the caller has access to.

Auth required: Yes (projects:read permission or JWT)

Parameter	Type	Description
`team_id`	string	Optional. Filter to a specific team.

// Response (200)
{
  "projects": [
    {
      "id": "uuid",
      "team_id": "uuid",
      "name": "My App",
      "slug": "my-app",
      "color": "#22c55e",
      "retention_days_events": null,
      "retention_days_metrics": null,
      "retention_days_funnels": null,
      "effective_retention_days_events": 120,
      "effective_retention_days_metrics": 365,
      "effective_retention_days_funnels": 365,
      "attachment_user_quota_bytes": null,
      "attachment_project_quota_bytes": null,
      "effective_attachment_user_quota_bytes": 262144000,
      "effective_attachment_project_quota_bytes": 5368709120,
      "issue_alert_frequency": null,
      "effective_issue_alert_frequency": "daily",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /v1/projects/:id

Get a single project with its apps.

Auth required: Yes (projects:read permission or JWT)

// Response (200)
{
  "id": "uuid",
  "team_id": "uuid",
  "name": "My App",
  "slug": "my-app",
  "color": "#22c55e",
  "retention_days_events": null,
  "retention_days_metrics": null,
  "retention_days_funnels": null,
  "effective_retention_days_events": 120,
  "effective_retention_days_metrics": 365,
  "effective_retention_days_funnels": 365,
  "attachment_user_quota_bytes": null,
  "attachment_project_quota_bytes": null,
  "effective_attachment_user_quota_bytes": 262144000,
  "effective_attachment_project_quota_bytes": 5368709120,
  "issue_alert_frequency": null,
  "effective_issue_alert_frequency": "daily",
  "created_at": "2024-01-01T00:00:00.000Z",
  "apps": [
    {
      "id": "uuid",
      "team_id": "uuid",
      "project_id": "uuid",
      "name": "iOS App",
      "platform": "apple",
      "bundle_id": "com.example.myapp",
      "client_secret": "owl_client_abc123...",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

POST /v1/projects

Create a new project within a team.

Auth required: Yes (projects:write permission or JWT, admin role required)

// Request
{
  "team_id": "uuid",
  "name": "My App",
  "slug": "my-app",
  "retention_days_events": 90
}

// Response (201)
{
  "id": "uuid",
  "team_id": "uuid",
  "name": "My App",
  "slug": "my-app",
  "color": "#22c55e",
  "retention_days_events": 90,
  "retention_days_metrics": null,
  "retention_days_funnels": null,
  "effective_retention_days_events": 90,
  "effective_retention_days_metrics": 365,
  "effective_retention_days_funnels": 365,
  "created_at": "2024-01-01T00:00:00.000Z"
}

A display color is auto-assigned on creation (picked from a palette of unused colors within the team). Use PATCH to override it. The request body does not accept color.

Field reference

Field	Type	Required	Description
`team_id`	string	Yes	The team this project belongs to.
`name`	string	Yes	Display name.
`slug`	string	Yes	URL-friendly identifier. Must match `^[a-z0-9-]+$`. Unique within a team.
`retention_days_events`	integer	No	Days to retain events. Default: 120.
`retention_days_metrics`	integer	No	Days to retain metric events. Default: 365.
`retention_days_funnels`	integer	No	Days to retain funnel events. Default: 365.

Slug reuse: if a soft-deleted project exists with the same slug in the same team, it is hard-deleted to free the slug.

Returns 409 if an active project with the same slug already exists.

PATCH /v1/projects/:id

Update a project's name, color, or data retention policies.

Auth required: Yes (projects:write permission or JWT, admin role required)

Field	Type	Required	Description
`name`	string	No	New display name.
`color`	string	No	Display color as `#RRGGBB` hex. Auto-assigned on creation; override to customize.
`retention_days_events`	integer or null	No	Days to retain events. `null` resets to default (120).
`retention_days_metrics`	integer or null	No	Days to retain metric events. `null` resets to default (365).
`retention_days_funnels`	integer or null	No	Days to retain funnel events. `null` resets to default (365).
`attachment_user_quota_bytes`	integer or null	No	Per-user attachment storage quota in bytes. `null` resets to default (250 MB).
`attachment_project_quota_bytes`	integer or null	No	Project-wide attachment storage quota in bytes. `null` resets to default (5 GB).
`issue_alert_frequency`	string or null	No	Issue notification cadence: `none`, `hourly`, `6_hourly`, `daily`, or `weekly`. `null` resets to default (`daily`).

At least one field must be provided.

// Request
{
  "name": "Renamed Project",
  "retention_days_events": 60
}

// Response (200)
{
  "id": "uuid",
  "team_id": "uuid",
  "name": "Renamed Project",
  "slug": "my-app",
  "color": "#22c55e",
  "retention_days_events": 60,
  "retention_days_metrics": null,
  "retention_days_funnels": null,
  "effective_retention_days_events": 60,
  "effective_retention_days_metrics": 365,
  "effective_retention_days_funnels": 365,
  "created_at": "2024-01-01T00:00:00.000Z"
}

DELETE /v1/projects/:id

Soft-delete a project and cascade to its apps, API keys, metric definitions, and funnel definitions.

Auth required: Yes (JWT only, admin role required. Agent keys receive 403.)

// Response (200)
{
  "deleted": true
}

Ready to get started?

Connect your agent via MCP or CLI and start tracking.

Get Started GitHub