# Retire a dataset

`DELETE /v1/datasets/defs/{def_id}`

Retire one dataset definition: it leaves the shelf. Same tombstone
contract as retiring a source — its pinned versions stay resolvable by id,
so a training run already holding one does not break. Sources are
untouched.

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

## Parameters

- `def_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` `DatasetDefRetireResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `404` Unknown dataset, or outside the caller's account
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
DatasetDefRetireResponse:
  properties:
    retired:
      type: boolean
      description: False when the dataset was already retired; the call is idempotent
    name:
      type: string
      description: Name the dataset had at retirement
    pinned_versions_retained:
      type: integer
      minimum: 0
      description: Pinned versions left resolvable by id, so running trainings survive
  type: object
  required:
    - retired
    - name
    - pinned_versions_retained
  title: DatasetDefRetireResponse
  description: Result of retiring a dataset definition.
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
```