# Versions_CompareVersions

`GET /v1/accounts/{account}/datasets/{dataset}/versions:compare`

What came in, went out or changed revision between two refs of one
dataset, and why. Paged over the changed episodes.

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

## Parameters

- `account` (path, string, required): The account id.
- `dataset` (path, string, required): The dataset id.
- `base` (query, string): The ref measured from: a tag, `stable` or a digest prefix. Empty
  means the newest tag (everything is new when there is none).
- `target` (query, string): The ref measured to; empty means `head`.
- `pageSize` (query, integer (int32)): At most this many changed episodes; 0 means 100, the maximum is 1000.
- `pageToken` (query, string): From a previous response's next_page_token.

## Responses

- `200` OK: `application/json` `qualia.v1.CompareVersionsResponse`
- `default` Default error response: `application/json` `google.rpc.Status`

## Schemas

```yaml
qualia.v1.CompareVersionsResponse:
  type: object
  properties:
    changes:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.CompareVersionsResponse_Change"
      description: One page of changed episodes.
    nextPageToken:
      type: string
      description: Empty on the last page.
    baseVersion:
      type: string
      description: The resolved base ("1.0", or empty when there was none).
    baseDigest:
      type: string
      description: Digest of the base.
    targetDigest:
      type: string
      description: Digest of the target.
    addedCount:
      type: string
      description: Episodes added, across every page.
    removedCount:
      type: string
      description: Episodes removed, across every page.
    changedCount:
      type: string
      description: Episodes in both at a different revision, across every page.
    reasonCounts:
      type: object
      additionalProperties:
        type: string
      description: Added, removed and changed counted per reason, "RULING" -> n, for the dialog's summary.
    draftNote:
      type: string
      description: A note drafted from the diff, for the tag dialog to pre-fill.
    suggestedVersion:
      type: string
      description: |-
        The tag name the dialog offers: the next minor ("1.0" first). Majors are
        a person's call.
  description: Response for Versions.CompareVersions.
qualia.v1.CompareVersionsResponse_Change:
  type: object
  properties:
    episode:
      type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}, in this dataset's scope.
    direction:
      enum:
        - DIRECTION_UNSPECIFIED
        - ADDED
        - REMOVED
        - CHANGED
      type: string
      description: Added or removed.
      format: enum
    reason:
      enum:
        - REASON_UNSPECIFIED
        - RULING
        - UPSTREAM_RULING
        - SOURCE_CHANGED
        - SOURCE_MOVED
        - ARRIVED
        - SPLIT
        - EDITED
      type: string
      description: Why.
      format: enum
    source:
      type: string
      description: The source it came through (mixtures).
    cut:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Episode_Cut"
      description: |-
        Present on immutable cut pieces. Identifies their original take and
        their order within its cut, so replacements can be paired across this
        flat direction/episode-ordered list (and across pages). The take uses
        this comparison's dataset scope, just as episode does.
  description: One episode that came in or went out.
qualia.v1.Episode_Cut:
  type: object
  properties:
    take:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/episodes/{episode}: the take it
        was cut from.
    takeIndex:
      readOnly: true
      type: integer
      description: The take's index in its upload (Episode.index of the take).
      format: int32
    piece:
      readOnly: true
      type: integer
      description: Its place among the take's pieces, from 1.
      format: int32
    pieceCount:
      readOnly: true
      type: integer
      description: How many pieces the take was cut into.
      format: int32
    startSeconds:
      readOnly: true
      type: number
      description: Where it starts, in seconds of the take's recording.
      format: double
    endSeconds:
      readOnly: true
      type: number
      description: Where it ends, in seconds of the take's recording.
      format: double
  description: |-
    Where a cut piece came from: an episode a version published from a draft
    that split or trimmed a take. It is the take's piece `piece` of
    `piece_count`, kept from `start_seconds` to `end_seconds` of the take's
    recording, and reads as the dashboard numbers it ("12.1": the take's
    index, then the piece's, from 1).
google.rpc.Status:
  oneOf:
    - $ref: "#/components/schemas/ApiError"
    - $ref: "#/components/schemas/GatewayError"
  description: "The body of a failed call: one of the two shapes below."
ApiError:
  title: API error
  type: object
  required:
    - code
    - message
    - retryable
    - details
  properties:
    code:
      type: string
      description: The gRPC code name in upper case, e.g. `NOT_FOUND`.
    message:
      type: string
    retryable:
      type: boolean
      description: Whether the same call may succeed if retried.
    details:
      type: array
      items:
        type: object
      description: "Empty, except when a dataset copy or move is refused: then one `google.rpc.ErrorInfo` with the refusal's `reason` code, its `domain` and, in `metadata`, the datasets it names."
  description: A refusal from the API itself.
GatewayError:
  title: Gateway error
  type: object
  required:
    - detail
  properties:
    detail:
      type: string
      description: What went wrong.
  description: A refusal from the gateway before the call reaches the API, for example `401` bad or missing API key, `403` key lacks the scope or environment closed, `413` body too large.
```