# Episodes_AssignTask

`POST /v1/accounts/{account}/datasets/{dataset}/episodes:assignTask`

Sets one task label on every selected episode of an upload in a single
publication: all of them or none. Episodes whose task already
reads that label are left as they are; the rest get one revision each and
share one TASK_ASSIGNED event. Selection runs over the upload's episodes,
which do not include the children of a split: a split parent takes the
label, and its children take it with it in the same publication.
Through a merged dataset the selection is split by the upload
that holds each episode: one such publication per upload.

- 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.

## Request body

Required: `application/json` `qualia.v1.AssignTaskRequest`

## Responses

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

## Schemas

```yaml
qualia.v1.AssignTaskRequest:
  required:
    - parent
    - selection
  type: object
  properties:
    parent:
      type: string
      description: "accounts/{account}/datasets/{dataset}: must be the upload."
    selection:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.EpisodeSelection"
      description: Which episodes, at most 10000.
    task:
      type: string
      description: |-
        The task label every selected episode should read. Required unless
        linked_task is set, when it defaults to that task's display_name.
    requestId:
      type: string
      description: |-
        Optional UUID4 identifying this logical edit. Reusing it with the same
        caller and request returns the original result; different input conflicts.
        When absent, each call starts a new logical edit.
    linkedTask:
      type: string
      description: |-
        accounts/{account}/tasks/{task}: link every selected episode to this
        task as well. A task of the dataset's account; NOT_FOUND
        otherwise. Empty leaves links as they are.
  description: Request for Episodes.AssignTask.
qualia.v1.EpisodeSelection:
  type: object
  properties:
    names:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.EpisodeNames"
      description: Episode names under the request's parent.
    filter:
      type: string
      description: A ListEpisodes filter over the parent (e.g. what the filter bar leaves).
  description: |-
    Which episodes a bulk ruling acts on: an explicit list, or a filter. Names
    must be under the request's parent (INVALID_ARGUMENT otherwise); a filter
    only ever matches the parent's own episodes (a mixture: its pool).
qualia.v1.EpisodeNames:
  type: object
  properties:
    names:
      type: array
      items:
        type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}, at most 10000.
  description: A list of episode names.
qualia.v1.AssignTaskResponse:
  type: object
  properties:
    assignedCount:
      type: integer
      description: Episodes whose task changed to the label, or whose link changed.
      format: int32
    unchangedCount:
      type: integer
      description: |-
        Selected episodes that already read the label (and the link), left
        unchanged.
      format: int32
    childrenFollowedCount:
      type: integer
      description: |-
        Split children of the relabelled episodes that took the label with their
        parent. A child is never selected or counted on its own.
      format: int32
  description: Response for Episodes.AssignTask.
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.
```