# Advisory in-flight upload heartbeat for the pending band

`POST /v1/datasets/upload/heartbeat`

Makes the chunk-transfer phase visible in /datasets/uploads — the only
upload phase no QDS artifact can see. Advisory: a miss costs a pending-band
entry, never an upload, so the SDK calls this best-effort.

The answer says whether the user has cancelled the upload; a
client that reads `cancelled: true` stops. (This route answered 204 with
no body before, and an SDK of that era never reads one.)

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

## Request body

Required: `application/json` `UploadHeartbeatBody`

## Responses

- `200` Successful Response: `application/json` `UploadHeartbeatResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
UploadHeartbeatBody:
  properties:
    repo_id:
      type: string
      format: uuid
    session_id:
      type: string
      format: uuid
    sequence:
      type: integer
      minimum: 1
    total_files:
      type: integer
      minimum: 0
      default: 0
    total_bytes:
      type: integer
      minimum: 0
      default: 0
    transferred_bytes:
      type: integer
      minimum: 0
      default: 0
    uploaded_bytes:
      type: integer
      minimum: 0
      default: 0
    staged_files:
      type: integer
      minimum: 0
      default: 0
    done:
      type: boolean
      default: false
    failed:
      type: boolean
      default: false
    failure_reason:
      type: string
      maxLength: 500
      default: ""
  additionalProperties: false
  type: object
  required:
    - repo_id
    - session_id
    - sequence
  title: UploadHeartbeatBody
UploadHeartbeatResponse:
  properties:
    cancelled:
      type: boolean
      default: false
  type: object
  title: UploadHeartbeatResponse
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
```