Projects API

All project endpoints require member token authentication via the Authorization header.

Logical services and checked consolidation are available from core 1.21.0. Prefer one project per system, reusing it across service repositories when access and privacy policies allow. See Projects and services for compatibility, preserved credentials and the checked merge workflow.

All project operations are also available via the CLI (debugbundle project list/create/update/delete) and MCP tools (list_projects, create_project, update_project, delete_project). See CLI Cloud Workflow and MCP Tools.

Logical services and consolidation

The API retains old project IDs as scoped views and provides these member operations. Service writes require current owner/admin access; merges require the same current owner/account and compatible access/settings. Hosted OpenAI remains read-only and does not expose merge or catalogue-management tools.

Method and path	Request / response
`GET /v1/projects/{id}/service-definitions`	Optional `limit` (1–200), `cursor`; `{services, next_cursor}`.
`POST /v1/projects/{id}/service-definitions`	`{name, description?, repository_url?, repository_root?}`; `{service}`.
`GET /v1/projects/{id}/service-definitions/{serviceId}`	`{service}`; the path ID is a logical `service_definition_id`.
`PATCH /v1/projects/{id}/service-definitions/{serviceId}`	Partial metadata update; nullable repository values restore project defaults.
`POST /v1/project-merges/preview`	`{target_project_id, source_project_ids, service_mappings}`; plan with digest, readiness, blockers and suggestions.
`POST /v1/project-merges`	`{request, plan_digest, idempotency_key}`; durable operation.
`GET /v1/project-merges/{id}`	Durable operation status.
`GET /v1/project-merges?idempotency_key=KEY`	Recover the original caller's operation after an uncertain outcome.
`GET /v1/project-merges/{id}/verification`	Read-only committed namespace/mapping verification.
`POST /v1/project-merges/{id}/resume`	Resume eligible work or post-commit verification.
`POST /v1/project-merges/{id}/cancel`	Cancel before commit; a committed merge cannot be cancelled.

Each mapping is {source_project_id, service_definition_id, name}. All IDs are UUIDs. Apply requires the exact checked request/digest and a stable idempotency key of 1–128 letters, digits, underscores or hyphens. Keep the same key/request on retries. Preview/apply bodies are limited to 1 MiB; other merge mutations retain the normal 256 KiB ceiling. Runtime resource/lock/deadline limits fail closed.

GET /v1/projects?project_id=LEGACY_ID returns its retained view with additive canonical_project_id, using current canonical membership. Ordinary lists show only canonical projects. Legacy project-wide management returns HTTP 409 project_consolidated with the canonical ID; safe existing-token revocation remains supported. GET /v1/services keeps {services} and adds optional offset (0–100000) alongside limit (1–100).

Merging defaults off (project_merge_not_enabled, HTTP 503). Invalid requests return 400; inaccessible operations return 404; stale previews, conflicts and ineligible transitions return 409. A conflict may carry operation_id: retain it and read status. A post-commit verification failure is not rollback. Server completion leaves repository adoption and deployed-runtime verification pending. See Projects and services for commands and recovery guidance.

List Projects

GET /v1/projects

curl https://api.debugbundle.com/v1/projects \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Response (200):

{
  "projects": [
    {
      "project_id": "proj_01HXYZ...",
      "organization_id": "org_01HABCDE...",
      "name": "Backend API",
      "slug": "backend-api",
      "environment_default": "production",
      "organization_plan": "team",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-03-15T14:30:00Z"
    }
  ]
}

Create Project

POST /v1/projects

curl -X POST https://api.debugbundle.com/v1/projects \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend API",
    "slug": "backend-api",
    "environment_default": "production"
  }'

Request Body:

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable project name.
`slug`	`string`	Yes	URL-safe identifier (lowercase, hyphens, no spaces).
`environment_default`	`string`	No	Editable project default used in setup snippets and prefilled project metadata. Common values: `production`, `staging`, `development`, but custom values are allowed.

Response (201):

{
  "project": {
    "project_id": "proj_01HNEW...",
    "organization_id": "org_01HABCDE...",
    "name": "Backend API",
    "slug": "backend-api",
    "environment_default": "production",
    "organization_plan": "team",
    "created_at": "2026-03-24T11:00:00Z"
  }
}

Get Project

GET /v1/projects/{id}

curl https://api.debugbundle.com/v1/projects/proj_01HXYZ... \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Response (200): Single project object.

Update Project

PATCH /v1/projects/{id}

curl -X PATCH https://api.debugbundle.com/v1/projects/proj_01HXYZ... \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend API v2",
    "environment_default": "staging"
  }'

Partial update — only the specified fields are changed.

Response (200): Updated project object.

Delete Project

DELETE /v1/projects/{id}

curl -X DELETE https://api.debugbundle.com/v1/projects/proj_01HXYZ... \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Response (204): No content.

Deleting a project permanently removes all incidents, bundles, tokens, webhooks, and alerts associated with that project. This operation cannot be undone.

Capture Policy

Each project has a capture policy that controls event ingestion behavior.

Get Capture Policy

GET /v1/projects/{id}/capture-policy

curl https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-policy \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Response (200):

{
  "policy": {
    "preset": "balanced",
    "capture_logs": "warning",
    "capture_request_events": "failures_only",
    "capture_breadcrumbs": "exception_only",
    "capture_probe_events": "buffer_only",
    "immediate_client_error_statuses": [],
    "immediate_client_error_path_rules": []
  },
  "overrides": {
    "capture_logs": null,
    "capture_request_events": null,
    "capture_breadcrumbs": null,
    "capture_probe_events": null,
    "immediate_client_error_statuses": null,
    "immediate_client_error_path_rules": null
  }
}

policy is the fully resolved capture policy. overrides preserves the raw saved state so clients can distinguish use preset default from explicit values such as [] for client error incidents.

Update Capture Policy

PATCH /v1/projects/{id}/capture-policy

curl -X PATCH https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-policy \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "investigative",
    "immediate_client_error_statuses": [401, 403, 409, 422],
    "immediate_client_error_path_rules": [
      { "status_code": 404, "path_pattern": "/checkout/*", "methods": ["GET", "POST"] }
    ]
  }'

Presets

Preset	Logs	Request Events	Breadcrumbs	Probe Events	Client Error Incidents
`minimal`	`error`	`failures_only`	`local_only`	`buffer_only`	`[]`
`balanced`	`warning`	`failures_only`	`exception_only`	`buffer_only`	`[]`
`investigative`	`info`	`all`	`standalone`	`standalone_when_activated`	`[401,403,409,422]`

Setting a preset changes the resolved defaults. Individual fields remain override-based:

Omitted fields keep their existing override state.
null clears an override and returns that field to the preset default.
immediate_client_error_statuses: [] means explicit none.
immediate_client_error_statuses: [401,403,409,422] promotes those 4xx statuses into immediate incidents.
immediate_client_error_path_rules promotes only matching 4xx status+path+method combinations, for example 404 under /checkout/*, without promoting every 404.
Unpromoted 4xx responses remain request telemetry/context when captured; they do not open incidents merely because they repeat.

Next Steps

API Ingestion — Event ingestion endpoint
Probes API — Activate debug probes
Alerts API — Alert rule management

Projects API

On this page