endpoints

Inference endpoints (M15) — hub-served inference for the skill / planner layer, never the reflex layer. Claimed by lucen serve, consumed by a device only through a signed approval bound to device + model digest + endpoint id, metered per session.

10 operations · 14 schemas

GET `/v1/endpoints`

List inference endpoints

listEndpoints · scope key:read

Endpoints the caller may see: their own and those billed to an org they belong to. No endpoint is public. Newest first; an unknown owner or model_repo is an empty page, not a 404. (M15)

Parameters

listEndpoints parameters
Name	In	Type	Description
`status`	query	`EndpointStatus`
`executor`	query	`RunExecutor`
`model_repo`	query	`string` length ≤ `130`	Only endpoints serving this `owner/slug`.
`owner`	query	`Handle`
`limit`	query	`integer` default `20` · ≥ `1` · ≤ `100`	Page size.
`cursor`	query	`string` length ≤ `512`	Opaque cursor from the previous page's `next_cursor`.

Responses

listEndpoints responses
Status	Description	Body
`200`	Page of endpoints.	`EndpointPage`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/endpoints`

Create an inference endpoint for a skill-layer model

createEndpoint · scope key:train

A model repo becomes a hub-served inference endpoint (M15). Invariant 1 of docs/ARCHITECTURE.md "Inference placement" is enforced here: the repo's ModelMeta.control_class must be skill or planner; a reflex model (a 50 Hz locomotion controller) answers 409 — nothing reflex-rate is ever served over a network by this hub — and a model that has declared no class answers 422 asking for one. The endpoint is pinned to one ONNX (onnx_path, or the repo's single root *.onnx) and its current sha256, exactly like a device approval request; the sha256 is what every session's approval token is later bound to. M17e — or to a checkpoint directory: a model with no ONNX export (the VLA smolvla_lora trains) is published as policy/ + lucen_manifest.json, and the endpoint is pinned to that directory (policy_path, or auto-detected when the repo holds no root ONNX) and to its lucen-checkpoint-v1 digest (EndpointArtifact); its control_class, contract fingerprint and params are read from the manifest, which the digest covers, and a manifest that says reflex is 409 whatever ModelMeta says. The hardware tier is chosen by the model's size, never by the caller: params × 2 bytes (bf16) plus 20 % headroom → the smallest tier that fits (a ≤ 3 B model lands on l4); params comes from the repo's io_contract.json / manifest, else from the body, else 422. executor: worker (the default) records the endpoint queued until lucen serve on the owner's own GPU box claims it — unpriced; executor: modal (W13) records the endpoint queued and the hub spawns the deployed endpoint function on the tier's GPU, which claims it with a public wss:// URL — on a deployment without MODAL_APP_NAME it answers 503 naming it and records nothing (never a fake running). key:train: an endpoint spends GPU time. Audited as endpoint.create.

Hosted execution (L0). executor: modal serves only owners in the deployment's HOSTED_OWNERS (default lucen; * = everyone); anyone else is 403 with errors[].type: forbidden.hosted_owner, naming the setting and lucen serve, and nothing is recorded. The estimate answers the same 403.

Request body

application/json · required · EndpointCreate

createEndpoint request body
Field	Type	Description
`model_repo`required	`string` length ≤ `129` · pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	`owner/slug` of a model repo visible to the caller, of control class `skill` or `planner`.
`onnx_path`	`FilePath \| null`	Which file in the repo the endpoint serves. Omit when the repo holds exactly one `*.onnx` at its root; required (`422`) when it holds several.
`policy_path`	`FilePath \| null`	M17e. The checkpoint directory the endpoint serves, for a model with no ONNX export (a VLA): LeRobot's `pretrained_model` layout, with `lucen_manifest.json` beside it — what `smolvla_lora` publishes. Omit when the repo holds `policy/` + `lucen_manifest.json` and no root `*.onnx`; required (`422`) when it holds both shapes. Mutually exclusive with `onnx_path` (`422`). `409` when the directory is empty or its manifest is missing, unparseable, names no `policy_format` of `lerobot` / `lerobot-peft`, or declares `control_class: reflex` (invariant 1 — the manifest is checked as well as `ModelMeta`).
`executor`	`RunExecutor \| null`	`worker` (default): `lucen serve` on the owner's own GPU box, unpriced. `modal`: a container the hub spawns (W13), priced by the tier; `503` on a deployment without `MODAL_APP_NAME`.
`owner`	`Handle \| null`	Who the endpoint is billed to (user or org). Omit for yourself.
`name`	`string \| null` length ≤ `64`	A label for the endpoint page.
`params`	`integer \| null` ≥ `1`	The model's parameter count, used only when neither the repo's `io_contract.json` nor the ONNX manifest declares `params` (a torch checkpoint the VLA template emits, before its manifest exists). Ignored when the repo declares one.
`max_hours`	`number \| null` > `0` · ≤ `720`	A wall-clock cap the server enforces on itself; null means no cap.
`budget_usd`	`number \| null` > `0`	A hard cap on the endpoint's total cost (priced executors only).

Responses

createEndpoint responses
Status	Description	Body
`201`	Endpoint recorded (`queued` for a `worker` executor).	`Endpoint`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

POST `/v1/endpoints/estimate`

Price an endpoint before creating it

estimateEndpoint · scope key:train

The same body as createEndpoint plus hours, validated identically (visibility, kind, control class, size), creating nothing. Answers the tier the model's size selects and rate_usd_per_hour × hours. A worker endpoint is cost_usd_max: 0, priced: false — the hub bills nothing for the owner's own GPU, and zero means "not charged", not "free GPU time" (M7-RL's rule). A modal estimate is priced even though that backend is not built: the price is true before "and it cannot run here yet" is. (M15)

Request body

application/json · required · EndpointEstimateRequest

estimateEndpoint request body
Field	Type	Description
`model_repo`required	`string` length ≤ `129` · pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`
`onnx_path`	`FilePath \| null`
`policy_path`	`FilePath \| null`	M17e. As on `EndpointCreate` — a checkpoint directory instead of an ONNX.
`executor`	`RunExecutor \| null`
`owner`	`Handle \| null`
`params`	`integer \| null` ≥ `1`
`hours`	`number` default `1` · > `0` · ≤ `720`	How many hours to price; the endpoint itself has no fixed duration.
`budget_usd`	`number \| null` > `0`

Responses

estimateEndpoint responses
Status	Description	Body
`200`	The estimate.	`EndpointEstimate`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

GET `/v1/endpoints/{endpoint_id}`

Get an inference endpoint

getEndpoint · scope key:read

One endpoint with its live counters (open sessions, chunks served, GPU-seconds, service and round-trip p95). An endpoint the caller may not see is 404, never 403. (M15)

Parameters

getEndpoint parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).

Responses

getEndpoint responses
Status	Description	Body
`200`	The endpoint.	`Endpoint`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json

DELETE `/v1/endpoints/{endpoint_id}`

Stop an inference endpoint

stopEndpoint · scope key:train

A queued endpoint is stopped at once (nothing ran, nothing to bill). A running one has a server on the owner's own machine, so the hub sets stop_requested_at and answers 202 with the endpoint still running; lucen serve sees the flag on its next report, closes every session and reports stopped, which is when the sessions' ledger rows are written. Idempotent; a terminal endpoint is 409. key:train, like cancelRun. Audited as endpoint.stop. (M15)

Parameters

stopEndpoint parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).

Responses

stopEndpoint responses
Status	Description	Body
`202`	Stopped, or stop requested; the endpoint as it now stands.	`Endpoint`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json

POST `/v1/endpoints/{endpoint_id}/claim`

Claim a queued worker endpoint (`lucen serve` protocol)

claimEndpoint · scope key:train

The run protocol, mirrored: compare-and-set queued → running on an endpoint whose executor is worker. Exactly one caller wins; an endpoint already claimed, terminal, or not a worker endpoint answers 409. The server states the websocket URL devices will connect to and the sha256 of the file it loaded, which must equal the endpoint's model_sha256 (422 otherwise — a server serving other bytes than the ones approvals are bound to is refused before any device can reach it). Records claimed_by, the claiming credential (only it may reportEndpoint afterwards — 409 for anyone else), claimed_at, started_at and the first heartbeat_at; audited as endpoint.claim. key:train: the server spends the owner's GPU on the owner's behalf. (M15)

Parameters

claimEndpoint parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).

Request body

application/json · required · EndpointClaim

claimEndpoint request body
Field	Type	Description
`worker`required	`string` length `1–128`	A name for the server — its hostname, or anything the operator will recognise.
`url`required	`string` length `6–512`	The websocket URL devices connect to (`ws://` or `wss://`), as reachable from the robot's network.
`model_sha256`required	`Sha256`

Responses

claimEndpoint responses
Status	Description	Body
`200`	Claimed; the endpoint as it now stands.	`Endpoint`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/endpoints/{endpoint_id}/report`

Report sessions, metering and state for a claimed endpoint

reportEndpoint · scope key:train

The server's one write path after claimEndpoint, every few seconds. The endpoint must be running (409 otherwise) and the caller must be the credential that claimed it (409). sessions[] carries the server's numbers per session — chunks served, GPU-seconds attributed as wall time × 1 / concurrent open sessions (a shared inference GPU is split evenly across the sessions it served, and the row says so), service-time p50/p95 — and state: closed when the device's link went away. status: stopped | failed is terminal: every still-open session is closed, each session's ledger row is written (priced by the model's tier on modal, 0 / unpriced on worker), cost_usd is summed onto the endpoint and endpoint.finish is audited. Read stop_requested_at on the returned endpoint: when set, close every session and report stopped. Every report refreshes heartbeat_at. (M15)

Parameters

reportEndpoint parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).

Request body

application/json · required · EndpointReport

reportEndpoint request body
Field	Type	Description
`status`	`EndpointReportStatus \| null`
`sessions`	`array of EndpointSessionState` items ≤ `200`
`error`	`string \| null` length ≤ `4000`
`log_chunk`	`string \| null` length ≤ `65536`	The server's log since the last report; kept on the endpoint's last-report record only.

Responses

reportEndpoint responses
Status	Description	Body
`200`	Recorded; the endpoint as it now stands.	`Endpoint`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

GET `/v1/endpoints/{endpoint_id}/sessions`

List an endpoint's sessions (metering)

listEndpointSessions · scope key:read

Newest first. Each session carries the server's metering (chunks served, GPU-seconds, service p50/p95), the device's own metering (chunks applied, round-trip p50/p95, deadline misses, degraded count) and, once closed, its cost. status narrows to open or closed. (M15)

Parameters

listEndpointSessions parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).
`status`	query	`EndpointSessionStatus`
`limit`	query	`integer` default `20` · ≥ `1` · ≤ `100`	Page size.
`cursor`	query	`string` length ≤ `512`	Opaque cursor from the previous page's `next_cursor`.

Responses

listEndpointSessions responses
Status	Description	Body
`200`	Page of sessions.	`EndpointSessionPage`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/endpoints/{endpoint_id}/sessions`

Open a session on an endpoint (a device, with a human's approval)

openEndpointSession · scope key:write

Invariant 2: an endpoint is consumed only through the consent layer. The caller is the robot-side driver (lucen-device, a write key that can see the device) and it must present the EdDSA approval token a human minted with createApproval on a request that named this endpoint (ApprovalRequestCreate.endpoint_id). The hub verifies the token against its own signing key and answers 403 when it is missing, unsigned, expired, bound to another endpoint, bound to another device, or when the approval is no longer issued / running — the same word for every refusal, so a token cannot be probed. It then checks the token's onnx_sha256 against the endpoint's model_sha256 (409 when the endpoint was re-created on other bytes) and that a server has claimed the endpoint (409 while queued). On success it records the session and returns the server's websocket url plus a short-lived session token (EdDSA, typ: lucen-session+jwt, exp = min(approval exp, now + ENDPOINT_SESSION_TTL_S)) the device presents to the server as openpi's api_key header; the server verifies it offline against GET /v1/devices/signing-key. No hub API key can open a session without a signed approval, which is the whole point. Audited as endpoint.session_open. (M15)

Parameters

openEndpointSession parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).

Request body

application/json · required · EndpointSessionOpen

openEndpointSession request body
Field	Type	Description
`device_id`required	`Id`
`approval_token`	`string \| null`	The EdDSA approval token a human minted for this device on a request naming this endpoint. Missing or invalid is `403`.

Responses

openEndpointSession responses
Status	Description	Body
`201`	Session opened; connect to `url` with `session_token`.	`EndpointSessionOpened`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/endpoints/{endpoint_id}/sessions/{session_id}/report`

The device's own metering for a session

reportEndpointSession · scope key:write

Only the device can measure a round trip, so it reports its side: chunks applied, round-trip p50/p95 in milliseconds, how many chunk deadlines were missed and how many times the local fail-safe fired (degraded_count). closed: true ends the session from the device's side (closed_reason says why: expired, local_cap, stopped, link_lost). The caller must be a credential that can see the session's device (404 otherwise); a closed session is 409. Each report replaces the device-side numbers — they are percentiles over the whole session, not deltas. key:write, like the driver's telemetry events. (M15)

Parameters

reportEndpointSession parameters
Name	In	Type	Description
`endpoint_id`required	path	`Id`	Endpoint id (`ep_...`).
`session_id`required	path	`Id`	Endpoint session id (`esess_...`).

Request body

application/json · required · EndpointSessionReport

reportEndpointSession request body
Field	Type	Description
`chunks_applied`	`integer \| null` ≥ `0`
`rtt_ms_p50`	`number \| null` ≥ `0`
`rtt_ms_p95`	`number \| null` ≥ `0`
`deadline_misses`	`integer \| null` ≥ `0`
`degraded_count`	`integer \| null` ≥ `0`
`closed`	`boolean` default `false`
`closed_reason`	`string \| null` length ≤ `64`

Responses

reportEndpointSession responses
Status	Description	Body
`200`	Recorded; the session as it now stands.	`EndpointSession`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

Schemas (14)

The schemas these operations reach before any other tag’s do. A type that links elsewhere is rendered on that tag’s page.

EndpointPage

object

EndpointPage fields
Field	Type	Description
`items`required	`array of Endpoint`
`next_cursor`required	`string \| null`

EndpointCreate

object

EndpointCreate fields
Field	Type	Description
`model_repo`required	`string` length ≤ `129` · pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	`owner/slug` of a model repo visible to the caller, of control class `skill` or `planner`.
`onnx_path`	`FilePath \| null`	Which file in the repo the endpoint serves. Omit when the repo holds exactly one `*.onnx` at its root; required (`422`) when it holds several.
`policy_path`	`FilePath \| null`	M17e. The checkpoint directory the endpoint serves, for a model with no ONNX export (a VLA): LeRobot's `pretrained_model` layout, with `lucen_manifest.json` beside it — what `smolvla_lora` publishes. Omit when the repo holds `policy/` + `lucen_manifest.json` and no root `*.onnx`; required (`422`) when it holds both shapes. Mutually exclusive with `onnx_path` (`422`). `409` when the directory is empty or its manifest is missing, unparseable, names no `policy_format` of `lerobot` / `lerobot-peft`, or declares `control_class: reflex` (invariant 1 — the manifest is checked as well as `ModelMeta`).
`executor`	`RunExecutor \| null`	`worker` (default): `lucen serve` on the owner's own GPU box, unpriced. `modal`: a container the hub spawns (W13), priced by the tier; `503` on a deployment without `MODAL_APP_NAME`.
`owner`	`Handle \| null`	Who the endpoint is billed to (user or org). Omit for yourself.
`name`	`string \| null` length ≤ `64`	A label for the endpoint page.
`params`	`integer \| null` ≥ `1`	The model's parameter count, used only when neither the repo's `io_contract.json` nor the ONNX manifest declares `params` (a torch checkpoint the VLA template emits, before its manifest exists). Ignored when the repo declares one.
`max_hours`	`number \| null` > `0` · ≤ `720`	A wall-clock cap the server enforces on itself; null means no cap.
`budget_usd`	`number \| null` > `0`	A hard cap on the endpoint's total cost (priced executors only).

EndpointEstimateRequest

object

EndpointEstimateRequest fields
Field	Type	Description
`model_repo`required	`string` length ≤ `129` · pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`
`onnx_path`	`FilePath \| null`
`policy_path`	`FilePath \| null`	M17e. As on `EndpointCreate` — a checkpoint directory instead of an ONNX.
`executor`	`RunExecutor \| null`
`owner`	`Handle \| null`
`params`	`integer \| null` ≥ `1`
`hours`	`number` default `1` · > `0` · ≤ `720`	How many hours to price; the endpoint itself has no fixed duration.
`budget_usd`	`number \| null` > `0`

EndpointEstimate

object

What an endpoint would cost per hour, on the tier its model's size selects.

EndpointEstimate fields
Field	Type	Description
`executor`required	`RunExecutor`
`tier`required	`string` one of `l4` · `a10g` · `a100` · `h100`	Selected from the model's size: `params × 2 bytes` + 20 % headroom → the smallest tier that fits. Never chosen by the caller.
`params`required	`integer`	The parameter count the tier was chosen from.
`vram_bytes`required	`integer`	`params × 2 × 1.2` — the VRAM the model is assumed to need in bf16 with headroom.
`rate_usd_per_hour`required	`number`	Billed hourly rate for the tier (4 decimal places); 0 for a `worker` endpoint.
`hours`required	`number`
`cost_usd_max`required	`number`	`rate_usd_per_hour × hours`, then `min(budget_usd)` when a budget is set.
`budget_usd`	`number \| null`
`capped_by_budget`	`boolean`
`priced`required	`boolean`	False when the hub does not bill the executor (`worker`) — zero is "not charged", not "free GPU time".
`artifact`	`EndpointArtifact`
`notes`	`array of string`	M17e. What `vram_bytes` does NOT cover, in sentences. Empty for an ONNX. For a checkpoint directory `vram_bytes` is still weights-only arithmetic (it selects the tier, invariant 5), and the notes state what has actually been measured while serving that model family — and, explicitly, what has not (e.g. "NOT measured on CUDA").

EndpointClaim

object

EndpointClaim fields
Field	Type	Description
`worker`required	`string` length `1–128`	A name for the server — its hostname, or anything the operator will recognise.
`url`required	`string` length `6–512`	The websocket URL devices connect to (`ws://` or `wss://`), as reachable from the robot's network.
`model_sha256`required	`Sha256`

EndpointReport

object

One progress or terminal report from the server. Every field is optional.

EndpointReport fields
Field	Type	Description
`status`	`EndpointReportStatus \| null`
`sessions`	`array of EndpointSessionState` items ≤ `200`
`error`	`string \| null` length ≤ `4000`
`log_chunk`	`string \| null` length ≤ `65536`	The server's log since the last report; kept on the endpoint's last-report record only.

EndpointSessionStatus

string

one of open · closed

EndpointSessionPage

object

EndpointSessionPage fields
Field	Type	Description
`items`required	`array of EndpointSession`
`next_cursor`required	`string \| null`

EndpointSessionOpen

object

EndpointSessionOpen fields
Field	Type	Description
`device_id`required	`Id`
`approval_token`	`string \| null`	The EdDSA approval token a human minted for this device on a request naming this endpoint. Missing or invalid is `403`.

EndpointSessionOpened

object

EndpointSessionOpened fields
Field	Type	Description
`session`required	`EndpointSession`
`url`required	`string`	The server's websocket URL.
`session_token`required	`string`	EdDSA JWT (`typ: lucen-session+jwt`), presented to the server as openpi's `api_key` header; verified there offline against the hub's signing key.
`expires_at`required	`string (date-time)`
`model_sha256`required	`Sha256`
`contract_fingerprint`required	`ContractFingerprint \| null`

EndpointSessionReport

object

The device's side of a session's metering; each report replaces the last.

EndpointSessionReport fields
Field	Type	Description
`chunks_applied`	`integer \| null` ≥ `0`
`rtt_ms_p50`	`number \| null` ≥ `0`
`rtt_ms_p95`	`number \| null` ≥ `0`
`deadline_misses`	`integer \| null` ≥ `0`
`degraded_count`	`integer \| null` ≥ `0`
`closed`	`boolean` default `false`
`closed_reason`	`string \| null` length ≤ `64`

EndpointSession

object

EndpointSession fields
Field	Type	Description
`id`required	`Id`
`endpoint_id`required	`Id`
`device_id`	`Id \| null`
`approval_id`	`Id \| null`
`status`required	`EndpointSessionStatus`
`opened_at`required	`string (date-time)`
`expires_at`	`string (date-time) \| null (date-time)`	When the session token dies — the approval's expiry or the hub's session TTL, whichever is sooner.
`closed_at`	`string (date-time) \| null (date-time)`
`closed_reason`	`string \| null`
`last_report_at`	`string (date-time) \| null (date-time)`
`chunks_served`required	`integer`	As the server reported.
`gpu_seconds`required	`number`	As the server attributed (wall × 1 / concurrent sessions).
`service_ms_p50`	`number \| null`
`service_ms_p95`	`number \| null`
`chunks_applied`	`integer \| null`	As the device reported.
`rtt_ms_p50`	`number \| null`
`rtt_ms_p95`	`number \| null`
`deadline_misses`	`integer \| null`
`degraded_count`	`integer \| null`	How many times the device's local fail-safe fired (hold on deadline miss or link loss).
`cost_usd`	`number \| null`	`gpu_seconds / 3600 × tier rate` once closed on a priced executor; 0 on `worker`.
`priced`required	`boolean`
`created_at`required	`string (date-time)`

EndpointReportStatus

string

one of running · stopped · failed

EndpointSessionState

object

The server's numbers for one session, replaced on every report.

EndpointSessionState fields
Field	Type	Description
`session_id`required	`Id`
`state`	`string` one of `open` · `closed` default `"open"`
`chunks_served`	`integer` default `0` · ≥ `0`
`gpu_seconds`	`number` default `0` · ≥ `0`	Wall time this session was open × 1 / the number of sessions open alongside it, summed per interval.
`service_ms_p50`	`number \| null`
`service_ms_p95`	`number \| null`
`closed_reason`	`string \| null` length ≤ `64`

endpoints

GET /v1/endpoints

Parameters

Responses

POST /v1/endpoints

Request body

Responses

POST /v1/endpoints/estimate

Request body

Responses

GET /v1/endpoints/{endpoint_id}

Parameters

Responses

DELETE /v1/endpoints/{endpoint_id}

Parameters

Responses

POST /v1/endpoints/{endpoint_id}/claim

Parameters

Request body

Responses

POST /v1/endpoints/{endpoint_id}/report

Parameters

Request body

Responses

GET /v1/endpoints/{endpoint_id}/sessions

Parameters

Responses

POST /v1/endpoints/{endpoint_id}/sessions

Parameters

Request body

Responses

POST /v1/endpoints/{endpoint_id}/sessions/{session_id}/report

Parameters

Request body

Responses

Schemas (14)

EndpointPage

EndpointCreate

EndpointEstimateRequest

EndpointEstimate

EndpointClaim

EndpointReport

EndpointSessionStatus

EndpointSessionPage

EndpointSessionOpen

EndpointSessionOpened

EndpointSessionReport

EndpointSession

EndpointReportStatus

EndpointSessionState

GET `/v1/endpoints`

POST `/v1/endpoints`

POST `/v1/endpoints/estimate`

GET `/v1/endpoints/{endpoint_id}`

DELETE `/v1/endpoints/{endpoint_id}`

POST `/v1/endpoints/{endpoint_id}/claim`

POST `/v1/endpoints/{endpoint_id}/report`

GET `/v1/endpoints/{endpoint_id}/sessions`

POST `/v1/endpoints/{endpoint_id}/sessions`

POST `/v1/endpoints/{endpoint_id}/sessions/{session_id}/report`