HuggingFace Compatibility

Foundry is compatible with the HuggingFace Hub API, allowing you to leverage existing ML workflows with minimal changes. By changing a single environment variable, the huggingface_hub library, Transformers, and Datasets libraries will use Foundry as their endpoint.

Quick Switch

import os
os.environ["HF_ENDPOINT"] = "https://your-foundry-instance.example.com"

# All subsequent code works with Foundry without modification
from huggingface_hub import hf_hub_download, login
from transformers import AutoModel, AutoTokenizer
from datasets import load_dataset

# Login (using your Foundry access token)
login(token="your_foundry_access_token")

# Download a file
model_path = hf_hub_download(repo_id="org/model-name", filename="model.safetensors")

# Load a model
model = AutoModel.from_pretrained("org/model-name")
tokenizer = AutoTokenizer.from_pretrained("org/model-name")

# Load a dataset
dataset = load_dataset("org/dataset-name")

Compatible API Endpoints

File Download (resolve)

GET /datasets/{owner}/{repo}/resolve/{ref}/{path}
GET /spaces/{owner}/{repo}/resolve/{ref}/{path}
GET /api/models/{owner}/{repo}/resolve/{ref}/{path}

Range requests and the HEAD method are supported
LFS files are redirected via Presigned URLs

Git LFS Batch API

POST /datasets/{owner}/{repo}.git/info/lfs/objects/batch
POST /spaces/{owner}/{repo}.git/info/lfs/objects/batch

Git LFS batch API for upload/download negotiation.

User Information

GET /api/whoami-v2

Returns HF-compatible user information (including organization list, in camelCase format).

Repository Metadata

HF-compatible repository metadata is provided through the Repository API:

Endpoint	Description
`/api/{type}/{owner}/{repo}/refs`	List branches and tags
`/api/{type}/{owner}/{repo}/tree/{ref}`	Retrieve file tree
`/api/{type}/{owner}/{repo}/commit/{revision}`	Commit information

Response format uses the same camelCase as HF Hub (lastModified, modelId, createdAt, etc.).

HF Import API

API for importing repositories from HuggingFace Hub into Foundry.

HF Access Token Management

Store Token:

PUT /api/auth/huggingface
Content-Type: application/json

{"token": "hf_xxxxxxxxxxxxxxxxxxxxxxxx"}

Retrieve Token:

GET /api/auth/huggingface

Response:

{
  "success": true,
  "data": {
    "has_token": true,
    "preview": "hf_xxx...xxxx"
  }
}

The raw token is never returned; the preview is formatted as the first 6 characters + ... + the last 4 characters.

Delete Token:

DELETE /api/auth/huggingface

HF Repository Search

GET /api/huggingface/search?q={query}&type={type}&limit={limit}

Parameter	Type	Required	Description
q	string	✓	Search query
type	string	✓	One of `model`, `dataset`, `space`
limit	number	-	Maximum number of results (default 10, max 50)

Example response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "meta-llama/Llama-2-7b",
        "type": "model",
        "author": "meta-llama",
        "name": "Llama-2-7b",
        "downloads": 123456,
        "likes": 789,
        "tags": ["pytorch", "transformers", "text-generation"],
        "private": false
      }
    ],
    "total": 1
  }
}

HF Repository Validation

GET /api/huggingface/validate?repo_id={repo_id}&type={type}

Returns whether the repository can be imported, along with metadata such as the file list and total size.

Create Repository via Import

POST /api/repos/create
Content-Type: application/json

{
  "repo_id": "myuser/my-imported-model",
  "repo_type": "model",
  "private": false,
  "from_huggingface": {
    "repo_id": "meta-llama/Llama-2-7b"
  }
}

Response (201 Created):

{
  "success": true,
  "data": {
    "repo_id": "myuser/my-imported-model",
    "type": "model",
    "import_status": "pending",
    "import_job_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Import Status Values:

Status	Description
`pending`	Queued
`in_progress`	Download/upload in progress
`completed`	Import complete
`failed`	Import failed

Error Codes

HF Token Errors

Code	Description
`INVALID_TOKEN_FORMAT`	Invalid HF token format (must start with `hf_`)
`TOKEN_TOO_SHORT`	Token too short (minimum 20 characters)

HF Search/Validation Errors

Code	Description
`INVALID_REPO_TYPE`	Type other than `model`/`dataset`/`space`
`INVALID_REPO_ID`	Not in `author/name` format
`HF_REPO_NOT_FOUND`	Repository not found on HF
`HF_ACCESS_DENIED`	Private or gated repository
`HF_RATE_LIMIT`	HF API rate limit exceeded
`HF_TOKEN_INVALID`	HF token expired or invalid

Import Errors

Code	Description
`IMPORT_ALREADY_IN_PROGRESS`	Import already in progress
`HF_TOKEN_REQUIRED`	HF token required for private repository

Response Format Differences

Foundry API uses two response formats:

API Type	Field Format	Example
Foundry native API	snake_case	`created_at`, `is_pinned`
HF-compatible API	camelCase	`lastModified`, `modelId`

HF-compatible responses may include extension fields prefixed with _foundry_*. The huggingface_hub library ignores these fields; only Foundry-specific clients make use of them.

Limitations

One-time Import: After import, the repository is not synchronized with the original HF repository
Space Runtime: Import only copies files; to run apps, use the Foundry Spaces Deploy feature
Gated Repositories: You must accept the license on the HuggingFace website before importing

Command Palette