API Reference

Version: 1.1.0

This document describes all REST API endpoints, request/response formats, and examples.

---

Health Check

curl http://localhost:8200/api/v1/health

{
  "status": "ok"
}

---

Models

List Models from a Hub - POST /api/v1/models/list

Lists models available on a hub using hub-specific filters and pagination. Supported hubs: huggingface, ultralytics, pipeline-zoo-models, geti.

# List HuggingFace models by author
curl -X POST http://localhost:8200/api/v1/models/list \
  -H "Content-Type: application/json" \
  -d '{
    "hub": "huggingface",
    "filters": {"author": "microsoft", "search": "phi"},
    "limit": 10,
    "offset": 0
  }'

# List Ultralytics models
curl -X POST http://localhost:8200/api/v1/models/list \
  -H "Content-Type: application/json" \
  -d '{
    "hub": "ultralytics",
    "filters": {"search": "yolov8"},
    "limit": 10
  }'

# List Geti™ models
curl -X POST http://localhost:8200/api/v1/models/list \
  -H "Content-Type: application/json" \
  -d '{
    "hub": "geti",
    "filters": {"project_name": "detection", "precision": "FP16"},
    "limit": 10
  }'

Request Fields:

Field	Type	Required	Description
hub	string	yes	Hub to list models from (huggingface, ultralytics, pipeline-zoo-models, geti)
filters	object	no	Hub-specific listing filters (see below)
limit	int	no	Max items to return (1–200, default 50)
offset	int	no	Items to skip for pagination (default 0)
override_credentials	object	no	Base64-encoded per-request credential overrides

Supported Filters by Hub:

Hub	Filter Fields
huggingface	author, search, tags
ultralytics	search
pipeline-zoo-models	search
geti	project_id, project_name, model_group_id, model_group_name, model_name, export_type, precision, model_format

Response:

{
  "hub": "huggingface",
  "items": [
    {
      "name": "microsoft/Phi-3.5-mini-instruct",
      "owner": "microsoft",
      "tags": ["text-generation"],
      "license": "mit",
      "gated": false,
      "requires_token": false
    }
  ],
  "total": 100,
  "limit": 10,
  "offset": 0
}

---

Download Models - POST /api/v1/models/download

Downloads one or more models from supported hubs and optionally converts them to OpenVINO IR format. Requests are processed asynchronously; job IDs are returned immediately.

Query Parameter:

Parameter	Type	Required	Description
download_path	string	yes	Base path/subdirectory for model downloads (relative to MODELS_DIR)

# Download a HuggingFace model
curl -X POST "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      {
        "name": "microsoft/Phi-3.5-mini-instruct",
        "hub": "huggingface",
        "type": "llm",
        "is_ovms": false
      }
    ]
  }'

# Download and convert to OpenVINO
curl -X POST "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      {
        "name": "microsoft/Phi-3.5-mini-instruct",
        "hub": "openvino",
        "type": "llm",
        "is_ovms": true,
        "config": {
          "precision": "int8",
          "device": "CPU",
          "cache_size": 10
        }
      }
    ]
  }'

# Download an Ollama model
curl -X POST "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [{"name": "deepseek-r1", "hub": "ollama"}]
  }'

# Download from a remote URL
curl -X POST "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      {
        "name": "wind-turbine-anomaly-detection",
        "hub": "remote-url",
        "config": {
          "url": "https://github.com/open-edge-platform/edge-ai-resources/raw/main/timeseries-udf-deployment-packages/{name}.tar"
        }
      }
    ]
  }'

# Download multiple models in parallel
curl -X POST "http://localhost:8200/api/v1/models/download?download_path=my-models" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      {"name": "microsoft/Phi-3.5-mini-instruct", "hub": "huggingface", "type": "llm"},
      {"name": "deepseek-r1", "hub": "ollama"}
    ],
    "parallel_downloads": true
  }'

Model Request Fields:

Field	Type	Required	Description
name	string	yes	Model name/ID (format is hub-specific)
hub	string	yes	Source hub (see Supported Hubs below)
type	string	no	Model type (determines conversion behavior)
is_ovms	boolean	no	Convert to OpenVINO IR format (default false)
revision	string	no	Specific model revision/version to download
config	object	no	Configuration for OpenVINO conversion (required if is_ovms is true)
override_credentials	object	no	Per-request credential overrides (takes precedence over env vars)
validate_credentials	boolean	no	Validate credentials before starting (default false)

Supported Hubs:

Hub	Description
huggingface	HuggingFace model hub
ollama	Ollama model registry
ultralytics	Ultralytics YOLO models
pipeline-zoo-models	Pipeline Zoo Models
omz	Open Model Zoo
openvino	OpenVINO model export
geti	Intel Geti™
hls	HLS model source
remote-url	Download from a remote URL

Model Types:

Type	Description
llm	Large language model
vlm	Vision-language model
embeddings	Embedding model
rerank	Reranking model
image_generation	Image generation model
text2speech	Text-to-speech model
speech2text	Speech-to-text model
vision	Vision model
3d-pose	3D pose estimation model
rppg	Remote photoplethysmography
ai-ecg	AI ECG model

Conversion Config Fields:

Field	Type	Required	Description
precision	string	no	Weight precision: int4, int8, fp16, fp32 (default int8)
device	string	no	Target device: CPU, GPU, NPU, or HETERO:GPU,CPU (default CPU)
cache_size	int	no	Cache size for model optimization
quantize	string	no	Ultralytics quantization dataset for INT8 export
overwrite_models	boolean	no	Overwrite an existing exported model (OpenVINO)
post_processing	object	no	Post-processing overrides for OMZ model-specific workflows

name Format by Hub:

• huggingface, ollama, openvino, geti, hls, remote-url: single model name

• ultralytics: single name, comma-separated names, or all

• pipeline-zoo-models: single name, comma-separated names, or all

• omz: single name or comma-separated names (all is not supported)

Response:

{
  "message": "Started processing 1 model(s)",
  "job_ids": ["download_abc123", "convert_def456"],
  "status": "processing"
}

Authentication Notes:

• HUGGINGFACEHUB_API_TOKEN is optional for public HuggingFace models

• HUGGINGFACEHUB_API_TOKEN is required for gated/private HuggingFace models and for conversion

• No authentication needed for Ollama, Ultralytics, Pipeline Zoo Models, Geti™, or HLS models

---

Upload Custom Model - POST /api/v1/models/upload

Upload a ZIP file containing model.xml and model.bin at the ZIP root.

curl -X POST http://localhost:8200/api/v1/models/upload \
  -F "file=@my_model.zip" \
  -F "model_name=my_custom_model" \
  -F "provider=geti" \
  -F "framework=openvino" \
  -F "precision=FP16"

Form Fields:

Field	Type	Required	Description
file	binary	yes	ZIP file containing model.xml and model.bin
model_name	string	yes	Model name (alphanumeric, ., _, -, spaces)
provider	string	no	Provider segment in target path
framework	string	no	Framework segment in target path
precision	string	no	Precision folder (e.g., FP16, FP32, INT8)

Validation:

• model_name allows A-Z a-z 0-9 . _ - <space>. Spaces are replaced with underscores. Must not start/end with . or contain ..

• File size limit enforced (default 500 MB via MAX_UPLOAD_SIZE_MB)

• Files are read in chunks (default 8 KB via UPLOAD_CHUNK_SIZE_KB)

• Returns 409 if the target model path already exists

Response:

{
  "status": "success",
  "message": "Model 'my_custom_model' uploaded successfully.",
  "job_id": "upload_abc123",
  "model_name": "my_custom_model",
  "model_path": "/opt/models/custom_uploaded_models/geti/openvino/my_custom_model/FP16"
}

---

Get Completed Model Results - GET /api/v1/models/results

Retrieve all completed model downloads and conversions.

curl http://localhost:8200/api/v1/models/results

{
  "results": [
    {
      "job_id": "download_abc123",
      "model_name": "BAAI/bge-small-en-v1.5",
      "hub": "huggingface",
      "operation_type": "download",
      "status": "completed",
      "model_path": "/opt/models/preloaded/BAAI/bge-small-en-v1.5",
      "is_ovms": false,
      "completion_time": "2026-07-16T08:31:10.000000"
    }
  ]
}

---

Get Jobs for a Model - GET /api/v1/models/jobs

Retrieve all jobs related to a specific model.

curl "http://localhost:8200/api/v1/models/jobs?model_name=microsoft/Phi-3.5-mini-instruct"

{
  "jobs": [
    {
      "id": "5f0d4eba-c79c-4d02-97a6-43c3d0168ca0",
      "operation_type": "download",
      "model_name": "microsoft/Phi-3.5-mini-instruct",
      "hub": "huggingface",
      "status": "completed",
      "output_dir": "/opt/models/preloaded",
      "start_time": "2026-07-16T08:30:00.000000",
      "completion_time": "2026-07-16T08:31:10.000000"
    }
  ]
}

---

Jobs

List All Jobs - GET /api/v1/jobs

Retrieve all in-memory jobs.

curl http://localhost:8200/api/v1/jobs

{
  "jobs": [
    {
      "id": "5f0d4eba-c79c-4d02-97a6-43c3d0168ca0",
      "operation_type": "download",
      "model_name": "BAAI/bge-small-en-v1.5",
      "hub": "huggingface",
      "output_dir": "/opt/models/preloaded",
      "status": "completed",
      "start_time": "2026-07-16T08:30:00.000000",
      "completion_time": "2026-07-16T08:31:10.000000",
      "plugin_name": "huggingface",
      "model_type": "embeddings"
    }
  ]
}

Get Job Status - GET /api/v1/jobs/{job_id}

Retrieve the status and details of a specific job.

curl http://localhost:8200/api/v1/jobs/5f0d4eba-c79c-4d02-97a6-43c3d0168ca0

{
  "id": "5f0d4eba-c79c-4d02-97a6-43c3d0168ca0",
  "operation_type": "download",
  "model_name": "BAAI/bge-small-en-v1.5",
  "hub": "huggingface",
  "output_dir": "/opt/models/preloaded",
  "status": "downloading",
  "start_time": "2026-07-16T08:30:00.000000",
  "plugin_name": "huggingface",
  "model_type": "embeddings"
}

Cancel a Job - POST /api/v1/jobs/{job_id}/cancel

Cancel a job that is in a cancellable state (queued, downloading, or converting).

curl -X POST http://localhost:8200/api/v1/jobs/download_abc123/cancel

{
  "message": "Job download_abc123 has been cancelled",
  "job_id": "download_abc123",
  "status": "canceled"
}

Job Statuses:

Status	Description
queued	Job is waiting to be processed
downloading	Model download in progress
converting	Model conversion in progress
completed	Job finished successfully
failed	Job encountered an error
canceled	Job was cancelled by the user

---

Plugins

List Available Plugins - GET /api/v1/plugins

Retrieve information about all available plugins, their capabilities, and status.

curl http://localhost:8200/api/v1/plugins

{
  "available_plugins": {
    "hub": [
      {
        "name": "huggingface",
        "type": "hub",
        "description": "Download models from HuggingFace",
        "capabilities": {
          "supports_parallel_downloads": true,
          "supports_listing": true,
          "listing_filter_fields": ["author", "search", "tags"]
        },
        "available": true
      }
    ]
  },
  "total_count": 8,
  "available_count": 6,
  "activation_instructions": "Enable/disable plugins via environment variables"
}

---

Endpoint Summary

Models (POST)

Endpoint	Description
POST /api/v1/models/list	List models available on a hub
POST /api/v1/models/download	Download and optionally convert models
POST /api/v1/models/upload	Upload a custom model ZIP file

Models (GET)

Endpoint	Description
GET /api/v1/models/results	Get completed model operations
GET /api/v1/models/jobs	Get jobs for a specific model

Jobs

Endpoint	Description
GET /api/v1/jobs	List all jobs
GET /api/v1/jobs/{job_id}	Get job status
POST /api/v1/jobs/{job_id}/cancel	Cancel a running or queued job

Other

Endpoint	Description
GET /api/v1/health	Health check
GET /api/v1/plugins	List available plugins

---

Response Models

Endpoint	Response Model
GET /api/v1/health	HealthResponse
POST /api/v1/models/list	ModelListResponse
POST /api/v1/models/download	DownloadResponse
POST /api/v1/models/upload	UploadResponse
GET /api/v1/models/results	ModelResultsResponse
GET /api/v1/models/jobs	JobListResponse
GET /api/v1/jobs	JobListResponse
GET /api/v1/jobs/{job_id}	Job
POST /api/v1/jobs/{job_id}/cancel	CancelJobResponse
GET /api/v1/plugins	PluginsResponse

---

HTTP Status Codes

Code	Scenario
200 OK	Request successful
400 Bad Request	Invalid hub, missing dependencies, or plugin not available
401 Unauthorized	Authentication failed for the hub
404 Not Found	Job or model not found
409 Conflict	Model already exists (upload)
413 Content Too Large	Uploaded file exceeds configured size limit
422 Unprocessable Entity	Validation error — malformed JSON, missing required fields
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error (unexpected exception)
501 Not Implemented	Hub does not support the requested operation (e.g., listing)
502 Bad Gateway	Upstream hub request failed

---

License

Copyright (C) 2025-2026 Intel Corporation

SPDX-License-Identifier: Apache-2.0