Skip to content
Qualia Docs

Import an exact Hugging Face dataset commit server-side

POST
/v1/datasets/import-hf
 
curl --request POST \
  --url https://example.com/v1/datasets/import-hf \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "idempotency_key": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "repo_id": "example", "revision": "example", "name": "example", "source_format": "lerobot_v2_1", "hf_token": "example" }'

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.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
account_id

Act within this account (the dashboard’s active account).

string | null format: uuid

Act within this account (the dashboard’s active account).

Request Body required

Section titled “Request Body required ”
Media type application/json
HuggingFaceImportBody

Server-side import of one exact public Hugging Face dataset commit.

object
idempotency_key
required
string format: uuid
repo_id
required
string
>= 3 characters <= 200 characters /^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$/
revision
required
string
/^[0-9a-f]{40}$/
name
required
string
>= 1 characters <= 100 characters
source_format
required
string
Allowed values: lerobot_v2_1 lerobot_v3
hf_token
string | null
>= 1 characters <= 512 characters

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Successful Response

Media type application/json
Example generated
example

401

Section titled “401 ”

Invalid or missing API key

Media type application/json
ErrorResponse

Standard error response.

object
detail
required

Error message describing what went wrong

string
Example generated
{
  "detail": "example"
}

409

Section titled “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

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Array<object>
ValidationError
object
loc
required
Location
Array<string | integer>
msg
required
Message
string
type
required
Error Type
string
input
ctx
Context
object
Example generated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}