projects

Delete Project

Delete a project, with safe and cascade-delete modes.

Accepts a :class:DeleteProjectRequest carrying a typed confirmation that must equal the project’s current name and an orphan_resources flag that selects between two explicit semantics:

Safe mode (orphan_resources=false, default): the endpoint refuses to delete a project that still owns resources and returns an HTTP 409 listing the blocking resource ids. Callers must deactivate each resource first via the regular DELETE /resources/... flow so the per-resource on_delete lifecycle runs against provider infrastructure.
Cascade mode (orphan_resources=true): the endpoint cascade- deletes every owned resource and the project row itself inside a single tenant-scoped SurrealDB transaction. No outbox events are emitted and no provider lifecycle is invoked, so the cloud infrastructure keeps running. This is the explicit opt-out for callers leaving pragma entirely.

Both paths run in a single BEGIN/COMMIT block. Because the projects and resources tables live in the same tenant namespace, the delete is atomic — either everything is removed or nothing is.

Raises: ProjectNotFoundError: If project not found in the caller’s tenant namespace. ConfirmationMismatchError: If confirmation does not match the project’s name. PlatformResourceError: If the caller is not allowed to delete a platform-managed project. ProjectHasResourcesError: If orphan_resources is False and the project still owns resources.

DELETE

/

projects

/

{project_id}

Delete Project

curl --request DELETE \
  --url https://api.example.com/projects/{project_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "confirmation": "<string>",
  "orphan_resources": false
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Path Parameters

project_id

string

required

Body

application/json

Request body for deleting a project.

Project deletion requires the caller to echo the project's current name as a typed confirmation token. The field is required — there is no boolean shortcut — and the server rejects any mismatch with HTTP 400 so a stale scripted call cannot silently destroy the wrong project.

Attributes: confirmation: Must equal the target project's name exactly. orphan_resources: When True, cascade-delete every resource in the project in the same transaction without invoking the per-resource on_delete provider lifecycle. Cloud infrastructure keeps running and pragma forgets it exists. When False (default), the endpoint refuses to delete a non-empty project and returns the list of blocking resources so the caller can deactivate them explicitly.

confirmation

string

required

Required string length: 1 - 200

orphan_resources

boolean

default:false

Opt in to cascade-wipe owned resources without running provider teardown. Defaults to False; non-empty projects are rejected unless this flag is True.

Response

Successful Response

Update ProjectUpdate a project's name. Platform JWT callers must be scoped to this exact project; the ``require_project_match`` dependency enforces JWT scope and verifies the project exists in the caller's tenant namespace. Returns: Updated project record. Raises: ProjectNotFoundError: If project not found or belongs to another organization. CrossProjectAccessError: If a platform JWT is scoped to a different project than the URL path.

Delete Project

curl --request DELETE \
  --url https://api.example.com/projects/{project_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "confirmation": "<string>",
  "orphan_resources": false
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}