# Pin a dataset version — freeze the def's query result

`POST /v1/datasets/versions`

Resolves the def's query NOW: frozen episode membership + blake3
membership/norm-stats hashes + the source repos' commit ids. A training
run pointed at the returned version id is reproducible.

Membership is whatever the query selects — quality never narrows it, so
a flagged episode the author picked is in the pin.

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

## Parameters

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

## Request body

Required: `application/json` `PinVersionBody`

## Responses

- `200` Successful Response: `application/json` `any`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `404` No such dataset def: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
PinVersionBody:
  properties:
    def_id:
      type: string
      format: uuid
    note:
      type: string
      maxLength: 4096
      default: ""
  additionalProperties: false
  type: object
  required:
    - def_id
  title: PinVersionBody
  description: |-
    Freeze a definition's current result as its next immutable version.

    There is deliberately no quality filter here. A pin freezes what the
    query selects, so it can never quietly drop episodes the author picked;
    dropping flagged work is curation's job, which mints its own version
    from a sealed analysis. Closed to extras, so a client still sending the
    retired ``exclude_flagged`` is refused rather than silently pinning
    everything under a name that promises otherwise.
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
```