# Episodes_AcquireEpisodeLease

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

Takes the take's edit lease for the caller and this tab. A
lease is per take: it holds through every dataset that reads it. One
lease per person: when the caller already holds it, the tab joins it and
it is renewed. It lapses 30 s after the last renewal. FAILED_PRECONDITION,
"episode is being edited by <name> until <time>", when another person
holds a live one; GetEpisode's `lease` names them.

- 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.
- `episode` (path, string, required): The episode id.

## Request body

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

## Responses

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

## Schemas

```yaml
qualia.v1.AcquireEpisodeLeaseRequest:
  required:
    - episode
    - tab
  type: object
  properties:
    episode:
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/episodes/{episode}: the take, in
        any dataset that reads it.
    tab:
      type: string
      description: "The caller's tab: a uuid the client makes on load."
  description: Request for Episodes.AcquireEpisodeLease.
qualia.v1.AcquireEpisodeLeaseResponse:
  type: object
  properties:
    lease:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Episode_Lease"
      description: The caller's lease.
  description: Response for Episodes.AcquireEpisodeLease.
qualia.v1.Episode_Lease:
  type: object
  properties:
    holder:
      readOnly: true
      type: string
      description: The holder's user id (as Actor.user).
    holderName:
      readOnly: true
      type: string
      description: |-
        The holder's display name at the time they took it; empty when they
        have none.
    expireTime:
      readOnly: true
      type: string
      description: When it lapses unless renewed.
      format: date-time
  description: |-
    Someone editing the take now: the lease AcquireEpisodeLease
    takes. One per take, so it reads the same from every scope.
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.
```