Model catalog API

Overview

The model catalog is the registry of ML models available in your workspace. Each record stores metadata about where the model runs (cloud, edge, hybrid), what inputs it accepts, and how to load it via the SDK. Public models are visible without authentication; private models are scoped to workspace members. Browse and load catalog rows from Python with cw.models — see ML Models (Python SDK). Typed create / update helpers are not on cw.models yet; call POST / PUT on this API or use generated cw.api.* wrappers until SDK methods land.

Method	Endpoint	Auth	Description
`GET`	`/api/v1/mlmodels`	✓	List models in your workspace (+ public)
`GET`	`/api/v1/mlmodels/public`	—	List public models (no auth required)
`GET`	`/api/v1/mlmodels/by-slug`	—	Get a model by unified slug
`GET`	`/api/v1/mlmodels/{uuid}`	✓	Get a model by UUID
`POST`	`/api/v1/mlmodels`	✓	Create a model record
`PUT`	`/api/v1/mlmodels/{uuid}`	✓	Update a model record
`DELETE`	`/api/v1/mlmodels/{uuid}`	✓	Delete a model record

`GET /api/v1/mlmodels`

List all ML model records visible to the authenticated user: workspace-private models plus any public ones.

Query parameters

Parameter	Type	Description
`deployment`	`string`	Filter by deployment (`cloud`, `edge`, `hybrid`)
`edge_compatible`	`bool`	When `true`, return only `edge` or `hybrid` models
`model_external_id`	`string`	Filter by exact external ID (e.g. `"yolov8n.pt"`)
`supported_level`	`string`	Filter by `driver`, `cloud`, `backend`, or `not_supported_yet`
`is_trainable`	`bool`	Filter trainable models only

Response — `200 OK`

Array of MLModelSchema.

[
  {
    "uuid": "a1b2c3d4-...",
    "slug": "acme/models/yolo26n",
    "name": "YOLO26n",
    "description": "Compact YOLO26 nano — 320 px, 4.4 ms CPU",
    "deployment": "edge",
    "is_edge_compatible": true,
    "is_cloud_compatible": false,
    "sdk_load_id": "yolo26n.pt",
    "model_external_id": "yolo26n.pt",
    "model_provider_name": "ultralytics",
    "edge_runtime": "ultralytics",
    "can_take_image_as_input": true,
    "can_take_video_as_input": true,
    "can_take_text_as_input": false,
    "can_take_audio_as_input": false,
    "can_take_action_as_input": false,
    "is_trainable": false,
    "visibility": "public",
    "tags": ["yolo", "detection"],
    "output_format": "json",
    "output_family": "structured_perception",
    "playground_kind": "edge",
    "workspace_uuid": "ws-uuid-...",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
]

`GET /api/v1/mlmodels/public`

List all public models. No authentication required. Accepts the same deployment query parameter as the authenticated list endpoint.

`GET /api/v1/mlmodels/by-slug`

Retrieve a model by its unified slug ({workspace-slug}/models/{entity-slug}).

Anonymous callers see public models. Authenticated callers additionally see private models they have access to.

Query parameters

Parameter	Type	Description
`slug`	`string` required	Full unified slug, e.g. `acme/models/yolo26n`

Response codes

Code	Meaning
`200`	Model found — returns MLModelSchema
`404`	Model not found or not visible to caller

`GET /api/v1/mlmodels/{uuid}`

Get a single model by UUID. Requires read access.

Path parameters

Parameter	Description
`uuid`	Model UUID

`POST /api/v1/mlmodels`

Create a new ML model record. Only admins can create public models.

Request body — `MLModelCreateSchema`

Field	Type	Default	Description
`name`	`string` required	—	Human-readable model name
`description`	`string` required	—	Description
`model_external_id`	`string` required	—	Filename or external registry key (e.g. `"yolov8n.pt"`)
`model_provider_name`	`string` required	—	Provider label (e.g. `"ultralytics"`, `"openai"`, `"local"`)
`deployment`	`string`	`"cloud"`	`cloud`, `edge`, or `hybrid`
`visibility`	`string`	`"private"`	`private`, `workspace`, `org`, `link`, or `public`
`workspace_uuid`	`string`	auto	Target workspace; omit to use the preferred workspace
`slug`	`string`	auto	Custom slug; auto-generated from name when omitted
`is_trainable`	`bool`	`false`	Whether the model supports fine-tuning
`can_take_image_as_input`	`bool`	`false`
`can_take_video_as_input`	`bool`	`false`
`can_take_text_as_input`	`bool`	`true`
`can_take_audio_as_input`	`bool`	`false`
`can_take_action_as_input`	`bool`	`false`
`edge_runtime`	`string`	`null`	Well-known runtime key (see `GET /mlmodels/edge-runtimes`) or free-text
`tags`	`string[]`	`[]`	Searchable tags
`metadata`	`object`	`{}`	Arbitrary metadata bag
`mapped_model_id`	`string`	`null`	Provider-internal model ID
`output_format`	`string`	`null`	Output format hint (`json`, `image`, `action`, …)

Example request

{
  "name": "YOLOv8 Nano",
  "description": "Lightweight object detector for warehouse inspection",
  "model_external_id": "yolov8n.pt",
  "model_provider_name": "ultralytics",
  "deployment": "edge",
  "edge_runtime": "ultralytics",
  "can_take_image_as_input": true,
  "can_take_video_as_input": true,
  "tags": ["detection", "vision"]
}

Response — `200 OK`

Returns the created MLModelSchema.

`PUT /api/v1/mlmodels/{uuid}`

Update a model. Write access required. Only admins can change visibility to/from public.

Request body — `MLModelUpdateSchema`

All fields are optional. Omitting a field leaves it unchanged.

Field	Type	Notes
`name`	`string`
`description`	`string`
`model_external_id`	`string`
`model_provider_name`	`string`
`deployment`	`string`	`cloud`, `edge`, `hybrid`
`visibility`	`string`	Admin-only for `public` changes
`is_trainable`	`bool`
`can_take_*_as_input`	`bool`	Any input capability flag
`edge_runtime`	`string`	Pass `""` to clear
`tags`	`string[]`	Replaces the entire tag list
`metadata`	`object`	Replaces the entire metadata bag
`mapped_model_id`	`string`
`output_format`	`string`

`DELETE /api/v1/mlmodels/{uuid}`

Delete a model record. Write access required. Only admins can delete public models.

Response — `200 OK`

{ "success": true }

MLModelSchema

Full model record returned by all read endpoints.

Field	Type	Description
`uuid`	`string`	UUID
`slug`	`string \| null`	Unified slug — `{workspace}/models/{name}`
`name`	`string`	Human-readable name
`description`	`string`
`model_external_id`	`string`	Filename or external ID
`model_provider_name`	`string`	Provider label
`deployment`	`string`	`cloud`, `edge`, or `hybrid`
`is_edge_compatible`	`bool`	True when deployment is `edge` or `hybrid`
`is_cloud_compatible`	`bool`	True when deployment is `cloud` or `hybrid`
`sdk_load_id`	`string \| null`	Key to pass to `cw.models.load()`
`edge_runtime`	`string \| null`	Runtime/framework label (e.g. `ultralytics`, `onnx`)
`edge_catalog_id`	`string \| null`	Resolved edge catalog ID (equals `sdk_load_id` for edge models)
`playground_kind`	`string \| null`	UI playground variant: `vlm`, `vlm-spatial-reasoner`, `vla`, `im2mesh`, `edge`
`output_format`	`string \| null`	Raw output format hint
`output_family`	`string \| null`	Canonical family: `structured_perception`, `action`, `text`, `image`, `mesh`
`visibility`	`string`	`private`, `workspace`, `org`, `link`, `public`
`tags`	`string[]`
`is_trainable`	`bool`
`can_take_image_as_input`	`bool`
`can_take_video_as_input`	`bool`
`can_take_text_as_input`	`bool`
`can_take_audio_as_input`	`bool`
`can_take_action_as_input`	`bool`
`allowed_structured_tasks`	`string[]`	Playground structured task IDs available for this model
`execution_surfaces`	`string[]`	Where the model can execute (`playground`, `edge_worker`, …)
`workspace_uuid`	`string`	Owner workspace
`created_at`	`datetime`
`updated_at`	`datetime`

Python SDK

from cyberwave import Cyberwave

cw = Cyberwave()

# List
for m in cw.models.list():
    print(m.slug, m.deployment, m.sdk_load_id)

# Filter by deployment
for m in cw.models.list(deployment="edge"):
    print(m.slug)

# Public models (no auth needed)
for m in cw.models.list_public():
    print(m.slug)

# Get by slug or UUID
m = cw.models.get("acme/models/yolo26n")
m = cw.models.get_by_uuid("a1b2c3d4-...")

# Delete
cw.models.delete("a1b2c3d4-...")

# Create / update — call the raw API client
cw.api.src_app_api_mlmodels_create_mlmodel(
    ml_model_create_schema={
        "name": "YOLOv8n",
        "description": "Edge detector",
        "model_external_id": "yolov8n.pt",
        "model_provider_name": "ultralytics",
        "deployment": "edge",
    }
)

MCP tools

cw_list_models(workspace_uuid?, deployment?)
cw_get_model(model_uuid)
cw_delete_model(model_uuid, execute?)

Model Playground API

Run inference, evaluate, download weights

Python SDK — ML Models

SDK reference for catalog + runtime

Edge Workers

Run edge models on hardware

ML Models (UI overview)

Dashboard walkthrough

SDKs & CLI

AI developer tools

Driver SDK

Workflow nodes

Config files & schemas

APIs

Changelog

Overview

`GET /api/v1/mlmodels`

Query parameters

Response — `200 OK`

`GET /api/v1/mlmodels/public`

`GET /api/v1/mlmodels/by-slug`

Query parameters

Response codes

`GET /api/v1/mlmodels/{uuid}`

Path parameters

`POST /api/v1/mlmodels`

Request body — `MLModelCreateSchema`

Example request

Response — `200 OK`

`PUT /api/v1/mlmodels/{uuid}`

Request body — `MLModelUpdateSchema`

`DELETE /api/v1/mlmodels/{uuid}`

Response — `200 OK`

MLModelSchema

Python SDK

MCP tools

Model Playground API

Python SDK — ML Models

Edge Workers

ML Models (UI overview)

​Overview

​GET /api/v1/mlmodels

​Query parameters

​Response — 200 OK

​GET /api/v1/mlmodels/public

​GET /api/v1/mlmodels/by-slug

​Query parameters

​Response codes

​GET /api/v1/mlmodels/{uuid}

​Path parameters

​POST /api/v1/mlmodels

​Request body — MLModelCreateSchema

​Example request

​Response — 200 OK

​PUT /api/v1/mlmodels/{uuid}

​Request body — MLModelUpdateSchema

​DELETE /api/v1/mlmodels/{uuid}

​Response — 200 OK

​MLModelSchema

​Python SDK

​MCP tools

​Related

Model Playground API

Python SDK — ML Models

Edge Workers

ML Models (UI overview)

Overview

`GET /api/v1/mlmodels`

Query parameters

Response — `200 OK`

`GET /api/v1/mlmodels/public`

`GET /api/v1/mlmodels/by-slug`

Query parameters

Response codes

`GET /api/v1/mlmodels/{uuid}`

Path parameters

`POST /api/v1/mlmodels`

Request body — `MLModelCreateSchema`

Example request

Response — `200 OK`

`PUT /api/v1/mlmodels/{uuid}`

Request body — `MLModelUpdateSchema`

`DELETE /api/v1/mlmodels/{uuid}`

Response — `200 OK`

MLModelSchema

Python SDK

MCP tools

Related