# Import an exact Hugging Face dataset commit server-side

`POST /v1/datasets/import-hf`

Admit one pinned Hugging Face commit as an upload attempt.

The import is the same durable object as an SDK upload — one attempt row,
one worker, one publication — so this route does what the SDK's own begin
does: resolve the destination repository, register the token the worker
will need, and call Begin. The idempotency key IS the operation id, so an
identical resubmission replays the same attempt instead of starting a
second one, and once that attempt has finished it returns it as it ended.

A new import is checked before anything runs: a name that already holds a
dataset is refused (an import only ever creates a dataset, so it could
only fail at publication), and the same import already running under
another key — a second tab, a double press — is joined rather than
started twice.

- 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 within this account (the dashboard's active account).

## Request body

Required: `application/json` `HuggingFaceImportBody`

## Responses

- `202` Successful Response: `application/json` `any`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `409` The name already holds a dataset (`dataset_name_taken`), another import into it is running (`dataset_name_importing`), or the idempotency key names another import (`idempotency_key_reused`).
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
HuggingFaceImportBody:
  properties:
    idempotency_key:
      type: string
      format: uuid
    repo_id:
      type: string
      maxLength: 200
      minLength: 3
      pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$
    revision:
      type: string
      pattern: ^[0-9a-f]{40}$
    name:
      type: string
      maxLength: 100
      minLength: 1
    source_format:
      type: string
      enum:
        - lerobot_v2_1
        - lerobot_v3
    hf_token:
      maxLength: 512
      minLength: 1
      type:
        - string
        - "null"
  additionalProperties: false
  type: object
  required:
    - idempotency_key
    - repo_id
    - revision
    - name
    - source_format
  title: HuggingFaceImportBody
  description: Server-side import of one exact public Hugging Face dataset commit.
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
```