---
title: "Import code or a dataset"
method: POST
path: "/v1/assets/import"
tags: ["Assets"]
---

# Import code or a dataset

`POST /v1/assets/import`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/assets/import`
- Auth: HTTP bearer

Import a GitHub repository, a Hugging Face dataset repository, or a public HTTPS file or archive. GitHub imports can use the team's connected GitHub account. URL imports use signed links for private downloads and reject tokens. GitHub, Hugging Face and URL imports may take up to ten minutes. It has no idempotency contract. After a timeout, inspect the asset list before repeating the request. Database connection queries return 202 after durable admission and export to Parquet or CSV in bounded workers. Poll the returned asset until ready or failed. Execution including queue time is bounded to ten minutes. reuse may return a ready export from the last 24 hours. New requests otherwise create fresh assets. Failed exports expose a safe error and retain their storage reservation until object cleanup succeeds.

## Request body

- AssetImportRequest: The server requires the source appropriate to kind. Import limits are deployment specific and returned by GET /v1/assets. Archives cannot contain links, special files, unsafe paths or more than 10000 files. Connection queries produce data.parquet or data.csv inside a normal input asset, with a 5 GB and 50 million row limit. Existing tenant storage quota also applies. Credentials remain on the control plane.
  - `kind` 'github' | 'huggingface' | 'url' | 'connection_query', required
  - `url` string: Public HTTPS direct download URL for kind=url. Private downloads use signed links.
  - `repo` string: owner/name for GitHub or a Hugging Face dataset. Matching HTTPS repository URLs are also accepted.
  - `ref` string: Repository revision. Omitted or empty selects main. Carriage returns and newlines are rejected.
  - `files` string[], nullable: Hugging Face dataset file patterns. Omitted selects recognized data file extensions. GitHub imports include the repository archive.
  - `token` string: Optional GitHub or Hugging Face credential. Rejected for URL imports.
  - `connection_id` string: Database connection name or ID for connection_query. Requires read or readwrite scope and an active pinned credential.
  - `sql` string: One SELECT or WITH statement, executed in a read-only transaction with a ten-minute timeout.
  - `format` 'parquet' | 'csv'
  - `branch` string: Optional Neon branch assertion. Must match the branch already verified on the connection.
  - `reuse` boolean: Reuse an eligible ready export for this tenant, connection, exact SQL apart from outer whitespace, branch and format from the last 24 hours.

## Response `200`

Eligible query export reused

- Asset
  - `id` string
  - `kind` string: Includes workspace_source for a generated workspace project revision. These copies use their separate included source pool.
  - `name` string
  - `state` string: Current asset state: importing, ready, failed, deleting or deleted.
  - `revision` string
  - `sha256` string
  - `stored_bytes` integer
  - `imported_bytes` integer
  - `created_at` string, date-time
  - `ready_at` string, date-time, nullable
  - `deleted_at` string, date-time, nullable
  - `export` ConnectionExport
    - `id` string
    - `connection_id` string
    - `asset_id` string
    - `query_hash` string
    - `branch` string
    - `format` 'parquet' | 'csv'
    - `row_count` integer
    - `bytes` integer
    - `created_at` string, date-time
    - `state` 'pending' | 'running' | 'cleanup' | 'ready': Durable export state. Failed exports release this record after object cleanup.
  - `error` string: Value-free terminal query export error. Failed assets remain observable after cleanup, with zero stored bytes once their reservation is released.
  - `workspace_source` WorkspaceSourceAlias
    - `source_id` string, required
    - `workspace_id` string, required
    - `source_revision` string, required
    - `exporter_version` string, required
    - `state` string, required
    - `removable` boolean, required: Whether this alias can currently be removed. Active workloads protect their source.
    - `shared_alias_count` integer, required: References sharing this physical source copy. Deleting one alias need not release bytes.

## Other responses

- `201`: Import complete and asset ready
- `202`: Database query admitted. Poll GET /v1/assets/{id} until ready or failed. Disconnecting does not cancel admitted work.
- `400`: Invalid import, source access, unsupported archive or size limit
- `409`: Storage quota reached or two imports already in progress
- `500`: Asset staging or commit failed
- `502`: Object storage unavailable
- `default`: Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)