---
title: "Receive Vm Facts"
method: POST
path: "/api/internal/servers/{server_id}/vm-facts"
tags: ["host-events"]
---

# Receive Vm Facts

`POST /api/internal/servers/{server_id}/vm-facts`

## Request

- Base URL: `https://api.maritime.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maritime.sh/api/internal/servers/{server_id}/vm-facts`
- Auth: none declared

Authenticates host facts and commits their ordered Agent status update.

## Path parameters

- `server_id` string, required

## Headers

- `X-API-Key` string

## Request body

- VMFactsChange: Orders one confirmed publication within its persistent sender generation.
  - `generation` integer, required
  - `revision` integer, required
  - `vm` VMFacts, required: Contains the existing public VM inspection fields without execution inputs.
    - `vmId` string, required
    - `lifecycleStage` 'unknown' | 'created' | 'running' | 'stopped' | 'sleeping' | 'deleted' | 'create_failed' | 'start_failed' | 'stop_failed' | 'delete_failed' | 'snapshot_failed' | 'restore_failed' | 'creating' | 'starting' | 'stopping' | 'deleting' | 'snapshotting' | 'restoring' | 'create_cleanup_in_progress' | 'start_cleanup_in_progress' | 'stop_cleanup_in_progress' | 'delete_cleanup_in_progress' | 'snapshot_cleanup_in_progress' | 'restore_cleanup_in_progress' | 'create_cleanup_failed' | 'start_cleanup_failed' | 'stop_cleanup_failed' | 'delete_cleanup_failed' | 'snapshot_cleanup_failed' | 'restore_cleanup_failed', required
    - `volumeId` string, nullable, required
    - `image` string, nullable, required
    - `vcpus` integer, nullable, required
    - `memMb` integer, nullable, required
    - `pid` integer, nullable, required
    - `cid` integer, nullable, required
    - `bootId` string, nullable, required
    - `rootId` string, nullable, required

## Response `204`

Successful Response

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/maritime/apis/maritime-api.md) - [All operations](https://skmtc.dev/maritime/apis/maritime-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maritime/apis/maritime-api/revisions/acd712090ad6?raw)