# Retire a source

`DELETE /v1/datasets/canonical/{dataset_id}`

Retire one source: it leaves the catalog, and its episodes leave the
lake and every facet count.

A TOMBSTONE, not a purge. Nothing is erased and no storage is reclaimed —
physical deletion is a separate step, and the schema agrees: pinned
DatasetVersions resolve through this source's episode identities and must
keep resolving. `pinned_versions_retained` reports how many do.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Parameters

- `dataset_id` (path, string (uuid), required)
- `account_id` (query, string | null (uuid)): Act on this account (active)

## Responses

- `200` Retired (or already retired — the call is idempotent): `application/json` `SourceRetireResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `404` Unknown source, or outside the caller's account
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
SourceRetireResponse:
  properties:
    retired:
      type: boolean
      description: False when the source was already retired; the call is idempotent
    dataset_name:
      type: string
      description: Name the source had at retirement
    episodes_hidden:
      type: integer
      minimum: 0
      description: Episodes that left the lake with it
    dataset_defs_retired:
      type: integer
      minimum: 0
      description: Source-bound dataset definitions retired alongside it
    pinned_versions_retained:
      type: integer
      minimum: 0
      description: Pinned DatasetVersions that still resolve through this source. Retirement is a tombstone, so these keep working and no bytes are freed.
  type: object
  required:
    - retired
    - dataset_name
    - episodes_hidden
    - dataset_defs_retired
    - pinned_versions_retained
  title: SourceRetireResponse
  description: Result of retiring a source.
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
HTTPValidationError:
  properties:
    detail:
      items:
        $ref: "#/components/schemas/ValidationError"
      type: array
  type: object
  title: HTTPValidationError
ValidationError:
  properties:
    loc:
      items:
        type:
          - string
          - integer
      type: array
      title: Location
    msg:
      type: string
      title: Message
    type:
      type: string
      title: Error Type
    input: {}
    ctx:
      type: object
      title: Context
  type: object
  required:
    - loc
    - msg
    - type
  title: ValidationError
```