Projects

Projects are containers that group together your journeys, agents, schedules, and other resources. They are simple organizational buckets with no behavior of their own.

Overview

A project is an organizational bucket. It groups journeys, agents, schedules, and other resources together. Projects have no behavior of their own. They exist so you can scope your work in whatever way makes sense for your team: by environment (staging, production), by application, by team, or however you prefer.

Every agent must belong to a project. When you create a journey or a schedule, you assign it to a project. The project's health board gives you an at-a-glance view of all journeys and their current pass/fail state.

POST /api/v1/projects

Create a new project

Parameters

Parameter	Type	In	Required	Description
`name`	string	body	Yes	Project name
`description`	string	body	No	Project description

Status Codes

Code	Description
`201`	Project created
`400`	Validation error
`401`	Unauthorized

Response Body

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Web App",
  "description": "Testing the checkout flow",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

API Key

name *

description

cURL

Response

GET /api/v1/projects

List projects

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Number of results to return (default: 20)
`cursor`	uuid	query	No	Cursor for pagination

Status Codes

Code	Description
`200`	OK
`401`	Unauthorized

Response Body

{
  "projects": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Web App",
      "description": "Testing the checkout flow",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "next_cursor": "770e8400-e29b-41d4-a716-446655440000"
}

API Key

limit

cursor

cURL

Response

GET /api/v1/projects/{id}

Get project by ID

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID

Status Codes

Code	Description
`200`	OK
`400`	Invalid UUID
`401`	Unauthorized
`404`	Project not found

Response Body

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Web App",
  "description": "Testing the checkout flow",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

API Key

id *

cURL

Response

PATCH /api/v1/projects/{id}

Update a project

Update project name and/or description. All fields optional.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID
`name`	string	body	No	New project name
`description`	string	body	No	New project description

API Key

id *

name

description

cURL

Response

DELETE /api/v1/projects/{id}

Delete a project

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID

Status Codes

Code	Description
`204`	Project deleted
`400`	Invalid UUID
`401`	Unauthorized
`404`	Project not found

API Key

id *

cURL

Response

PUT /api/v1/projects/{id}/webhook

Set project webhook

Configures a per-project webhook URL. Notifications for test runs and site discoveries in this project will be sent here instead of the global webhook.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID
`url`	string	body	Yes	Webhook URL (e.g. Slack Incoming Webhook)
`secret`	string	body	No	Optional HMAC signing secret

Status Codes

Code	Description
`204`	Webhook configured
`400`	Validation error
`401`	Unauthorized
`404`	Project not found

API Key

id *

url *

secret

cURL

Response

GET /api/v1/projects/{id}/webhook

Get project webhook

Returns whether the project has a webhook configured and its URL. The secret is never returned.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID

Status Codes

Code	Description
`200`	OK
`400`	Invalid UUID
`401`	Unauthorized
`404`	Project not found

Response Body

{
  "has_webhook": true,
  "url": "https://hooks.slack.com/services/T.../B.../xxx"
}

API Key

id *

cURL

Response

DELETE /api/v1/projects/{id}/webhook

Delete project webhook

Removes the per-project webhook. Notifications will fall back to the global webhook if configured.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Project ID

Status Codes

Code	Description
`204`	Webhook removed
`400`	Invalid UUID
`401`	Unauthorized
`404`	Project not found

API Key

id *

cURL

Response