Skip to content
Docs
Console

Page and section titles. Use your browser's find for words inside a page.

Deployments

Read deployment phases and check results. Start deployments in the console.

GET /v1/deployments

Authorization

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

Request

Request · cURL
curl "https://api.boardwalk.cloud/v1/deployments?limit=50" \
  -H "Authorization: Bearer $BOARDWALK_API_KEY"

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.
model_idstringoptional
Internal model ID.
statusstringoptional
Filter bucket: running, succeeded, failed, or stopped. Responses return the actual phase name.

Response

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

200 · application/json
{
  "object": "list",
  "data": [
    {
      "id": "dep_example",
      "object": "deployment",
      "model_id": "mdl_example",
      "model": "support-agent",
      "status": "screening",
      "failure_detail": null,
      "created_at": "2026-09-16T00:00:00.000Z",
      "updated_at": "2026-09-16T00:00:00.000Z",
      "ended_at": null,
      "revision_id": null,
      "hf_revision": "0123456789abcdef0123456789abcdef01234567",
      "started_by_user_id": "user_example"
    }
  ],
  "next_cursor": null
}
object"list"
Object type.
dataobject[]
Records ordered newest first.
Child fields
idstring
Deployment ID.
object"deployment"
Object type.
model_idstring
Internal model ID.
modelstring
Callable model name.
statusstring
Actual phase: screening, ingesting, probing, staging, checking, activating, activated, failed, or cancelled.
failure_detailstring | null
Redacted failure explanation.
created_atstring
ISO 8601 start time.
updated_atstring
ISO 8601 last update time.
ended_atstring | null
ISO 8601 completion time; null while running.
revision_idstring | null
Associated configuration revision.
hf_revisionstring | null
Pinned weight commit.
started_by_user_idstring | null
User who started the deployment, when known.
next_cursorstring | null
Pass as cursor for the next page. Null marks the end.

Retrieve one record

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

idpath · stringrequired
Record ID from a list response.
Request · cURL
curl https://api.boardwalk.cloud/v1/deployments/dep_example \
  -H "Authorization: Bearer $BOARDWALK_API_KEY"
200 · application/json
{
  "id": "dep_example",
  "object": "deployment",
  "model_id": "mdl_example",
  "model": "support-agent",
  "status": "screening",
  "failure_detail": null,
  "created_at": "2026-09-16T00:00:00.000Z",
  "updated_at": "2026-09-16T00:00:00.000Z",
  "ended_at": null,
  "revision_id": null,
  "hf_revision": "0123456789abcdef0123456789abcdef01234567",
  "started_by_user_id": "user_example",
  "phases": [
    { "status": "screening", "at": "2026-09-16T00:00:00.000Z" }
  ],
  "checks": [],
  "revision": null
}
phasesobject[]
Detail response only: recorded phase transitions.
Child fields
statusstring
Phase name.
atstring
ISO 8601 transition time.
checksobject[]
Detail response only: check results.
Child fields
namestring
Check name.
passedboolean
Whether the check passed.
detailstring
Additional detail, when recorded.
revisionobject | null
Detail response only: associated configuration.
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.
gpu_poolstring
GPU card class it serves on.
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.
verified_atstring | null
ISO 8601 time the revision passed its checks.

Preview a deployment

POST /v1/deployment-previews requires deployments:write. Send a source and optional serving settings. It reads the repository using the key creator’s Hugging Face connection and returns kind: derivedwith the pinned commit and fit, or kind: refused with a reason and remedy. Preview creates no deployment and reserves no GPUs.

Create a deployment

POST /v1/deployments requires deployments:write and an Idempotency-Key header. serve defaults to true, which additionally requires models:write. Use serve: false to prepare a checked candidate without changing the live model name. Deployment requires a first purchase.

Deploy a candidate
curl https://api.boardwalk.cloud/v1/deployments \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-release-124" \
  -d '{"model_name":"support","source":{"kind":"hugging_face","repo":"acme/support"},"serving":{"hold_seconds":5},"serve":false}'
model_namestringoptional
Name of a new model. Defaults to a name derived from the repository.
sourceobject
For a new model: kind: hugging_face, repo: owner/name, and optional ref (branch, tag, or commit). Only Hugging Face is supported.
model_idstringoptional
Redeploy an existing model instead. With model_id, omit source and model_name; optionally send ref.
servingobjectoptional
Optional runtime, host_class, max_context, kv_cache_dtype, hold_seconds, yarn:{factor,original_context?}, and validated engine flags. A redeploy retains previous serving settings when omitted.
servebooleanoptional
Default true requires models:write too. False checks a candidate without moving the live name.
202 Accepted
{
  "id": "deployment-id",
  "object": "deployment",
  "model_id": "model-id",
  "revision_id": null,
  "status": "screening",
  "status_url": "/v1/deployments/deployment-id"
}

Poll status_url with deployments:read. The deployment persists independently of the HTTP request. Retrying the same organization-scoped idempotency key and normalized input returns the same operation; changed input returns 409. Keys contain 1–128 letters, digits, dots, underscores, colons or hyphens. Replaying a deployment whose model was deleted returns 404, without recreating it.

Cancel a deployment

POST /v1/deployments/{id}/cancel requires deployments:write. Send no body or {}. It returns {"id":"deployment-id","cancelled":true}. Only the named run is cancelled; an old ID cannot stop a newer run. A finished run returns 409. The model remains stored; cancellation does not release reserved capacity.

Deployment events

GET /v1/deployments/{id}/events requires deployments:read and accepts no query parameters. It returns a finite JSON snapshot with deployment_id and data entries containing phase and entered_at. Poll alongside deployment details to follow progress.

Errors

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