Models

Read your organization\u2019s model inventory, including pending and disabled models.

GET /v1/models

Authorization

Authorizationheader · string: Bearer $BOARDWALK_API_KEY. Requires models:read.

Request

import json
from urllib.request import Request, urlopen

request = Request(
    "https://api.boardwalk.cloud/v1/models?limit=50",
    headers={"Authorization": "Bearer your-api-key"},
)
with urlopen(request, timeout=240) as response:
    print(json.load(response))

Query parameters

cursorstringoptional: Opaque next_cursor from the previous page, at most 256 characters. Keep all other filters unchanged.
limitintegeroptional: Page size from 1 to 200. Default: 50.
statusstringoptional: pending, active, or disabled.
visibilitystringoptional: public or private.
qstringoptional: Model search text, at most 120 characters.

Response

Example response. IDs, token counts, and rates are illustrative.

{
  "object": "list",
  "data": [
    {
      "id": "mdl_example",
      "object": "org_model",
      "slug": "support-agent",
      "display_name": "Support agent",
      "status": "pending",
      "visibility": "private",
      "hf_repo": "your-org/support-agent",
      "hf_revision": "0123456789abcdef0123456789abcdef01234567",
      "created_at": "2026-09-16T00:00:00.000Z",
      "updated_at": "2026-09-16T00:00:00.000Z",
      "revision": null
    }
  ],
  "next_cursor": null
}

object"list"

Object type.

dataobject[]

Records ordered newest first.

Child fields

idstring

Internal model ID. Use this in organization detail paths.

object"org_model"

Object type.

slugstring

Callable model ID for inference.

display_namestring

Display name.

statusstring

pending, active, or disabled.

visibilitystring

public or private.

hf_repostring

Source repository.

hf_revisionstring

Weight revision.

created_atstring

ISO 8601 creation time.

updated_atstring

ISO 8601 last update time.

revisionobject | null

Serving configuration, when available.

Child fields

idstring

Configuration revision ID.

statusstring

draft, active, or superseded.

hf_revisionstring

Pinned weight commit.

dtypestring

Serving precision.

quantizationstring

Quantization method, or none.

max_model_leninteger

Combined input and output token limit.

enginestring

Serving engine.

engine_versionstring

Pinned engine version.

autoscalingobject

Saved target_concurrency and max_concurrency policy, in requests per replica. Empty uses automatic behavior.

engine_settingsobject

The customer's requested engine flags.

cardstring

The card class it serves on, in whatever size of host the fleet holds.

gpu_countinteger

GPUs in the configuration.

pricesobject

Per-token rates, set for catalog models. A revision you deploy has zero rates, which are not a quote: it bills GPU time. Draft prices are not active rates.

Child fields

input_micros_per_mtokstring: Input rate. Integer micro-dollars per million tokens.
output_micros_per_mtokstring: Output rate. Integer micro-dollars per million tokens.
cache_read_micros_per_mtokstring: Cache-read rate. Integer micro-dollars per million tokens.
cache_write_micros_per_mtokstring: Cache-write rate. Integer micro-dollars per million tokens.

input_modalitiesstring[]

What a prompt may hold: "text", plus "image" or "audio" once the revision's deploy check served them.

verified_atstring | null

ISO 8601 time the revision passed its checks.

next_cursorstring | null

Pass as cursor for the next page. Null marks the end.

Retrieve one record

GET /v1/models/{id} returns one object directly, without the list envelope. It accepts no query parameters.

idpath · stringrequired: Record ID from a list response.

curl https://api.boardwalk.cloud/v1/models/mdl_example \
  -H "Authorization: Bearer $BOARDWALK_API_KEY"

{
  "id": "mdl_example",
  "object": "org_model",
  "slug": "support-agent",
  "display_name": "Support agent",
  "status": "pending",
  "visibility": "private",
  "hf_repo": "your-org/support-agent",
  "hf_revision": "0123456789abcdef0123456789abcdef01234567",
  "created_at": "2026-09-16T00:00:00.000Z",
  "updated_at": "2026-09-16T00:00:00.000Z",
  "revision": null
}

Detail fields match the object in data above.

Checked revisions

GET /v1/models/{id}/revisions requires models:read. It returns checked revision objects with data and next_cursor. Use limit and cursor to page newest first. A candidate deployed with serve: false is callable as name@revision before activation.

Pins use Boardwalk revision IDs, which include the runtime and serving settings. Hugging Face commits identify source weights. Stopped models refuse pinned requests, and catalog pins must refer to an active published revision.

Activate or roll back

POST /v1/models/{id}/activations requires models:write. Send {"revision_id":"checked-revision-id","now":false}. The revision must be checked and belong to this model. Normally a promotion warms the revision before moving the live name when another revision serves; now: true switches immediately for rollback. The response includes activated and promoting.

Stop, resume, or delete

Endpoint	Permission	Result
`POST /v1/models/{id}/stop-serving`	`models:write`	204; stops admission and cancels a running deployment.
`POST /v1/models/{id}/resume-serving`	`models:write` and `deployments:write`	200; resumes a checked model or starts a deployment.
`DELETE /v1/models/{id}`	`models:write`	204; stops and deletes the model, retaining billing records and deployment identities.

Send no body or {}. Resume returns model_id, resumed: true, and a nullable deployment_id. If a resume deployment cannot start, the model stays stopped. Stop and delete need no credits. Reserved capacity remains shared across the organization and can keep billing after a model is stopped or deleted; adjust it separately.

Errors

Errors use the shared error format. Save the x-request-id response header for receipts and support.