---
title: "Initialize huggingface sandbox with data"
method: POST
path: "/sandbox/huggingface/{sandbox_id}/initialize"
tags: ["sandbox"]
---

# Initialize huggingface sandbox with data

`POST /sandbox/huggingface/{sandbox_id}/initialize`

## Request

- Base URL: `https://api.klavis.ai`
- URL: `https://api.klavis.ai/sandbox/huggingface/{sandbox_id}/initialize`
- Auth: HTTP bearer

Initialize the sandbox with huggingface-specific data following the defined schema.

## Path parameters

- `sandbox_id` string, required: The unique sandbox identifier

## Query parameters

- `init_default_data` boolean: If true, use default test data for initialization

## Request body

- HuggingFaceDataInput: Complete HuggingFace sandbox data structure. Hierarchy: - Repos contain Files
  - `repos` HuggingFaceRepo[], nullable: List of HuggingFace repositories
    - `name` string, required: Repository name (without namespace, e.g., 'MyAwesomeModel-TestRepo')
    - `repo_type` string, nullable: Repository type: 'model', 'dataset', or 'space'
    - `description` string, nullable: Repository description
    - `private` boolean, nullable: Whether the repository is private
    - `files` HuggingFaceFile[], nullable: Files to upload to the repository
      - `path` string, required: File path within the repository (e.g., 'README.md', 'config.json', 'figures/fig1.png')
      - `content` string, nullable: Text content of the file (for text files). Mutually exclusive with url.
      - `url` string, nullable: URL to download binary content from (for binary files). Mutually exclusive with content.

## Response `200`

Successful Response

- InitializeSandboxResponse: Response model for sandbox initialization
  - `sandbox_id` string, required: Sandbox identifier
  - `status` 'idle' | 'occupied' | 'error', required: Status of a sandbox instance - matches database enum
  - `message` string, required: Initialization result message

## Other responses

- `422`: Validation Error

## Changes

- **2026-02-25** `cb885110e808`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/klavis-ai/apis/klavis-ai-https-www-klavis-ai/changes/sandbox/huggingface/:sandbox_id/initialize/post.md)

---

[API](https://skmtc.dev/klavis-ai/apis/klavis-ai-https-www-klavis-ai.md) - [All operations](https://skmtc.dev/klavis-ai/apis/klavis-ai-https-www-klavis-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/klavis-ai/apis/klavis-ai-https-www-klavis-ai/revisions/1f05ced7280f?raw)