--- title: "Create Podman Host" method: POST path: "/podman-host" tags: ["Podman Host"] --- # Create Podman Host `POST /podman-host` ## Request - Base URL: `https://oneuptime.com/api` - URL: `https://oneuptime.com/api/podman-host` - Auth: API key in header `APIKey` - TypeScript: (a function with typed inputs; its response is checked against the schema) Endpoint to create a new Podman Host ## Request body - object - `data` PodmanHostCreateSchema, required: Create schema for PodmanHost model. Create - `projectId` string, uuid: ID of your OneUptime Project in which this object belongs. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `name` string, required: Friendly name for this Podman host. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `description` string: Friendly description for this Podman host. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `hostIdentifier` string, required: Unique identifier for this Podman host, sourced from the host.name OTel resource attribute. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `isArchived` boolean: Is this Podman host archived? Archived Podman hosts are hidden from lists but keep collecting telemetry. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `labels` object[]: Labels to group and filter by. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `id` string - `retainTelemetryDataForDays` number: Number of days to retain telemetry data for this Podman host. Leave blank to use the project-wide default. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `telemetryRetentionConfig` object: Per-pillar retention overrides for this Podman host (logs by severity, traces by status, metrics, profiles). Unset fields fall back to the Podman host default, then the project's retention settings. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] ## Response `201` Created successfully - object - `data` PodmanHostReadSchema: Read schema for PodmanHost model. Read - `_id` string, uuid: ID of this object. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `createdAt` object: Date and Time when the object was created. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `updatedAt` object: Date and Time when the object was updated. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `deletedAt` object: Date and Time when the object was deleted. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `projectId` string, uuid: ID of your OneUptime Project in which this object belongs. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `name` string, required: Friendly name for this Podman host. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `slug` string: Friendly globally unique name for your object. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `description` string: Friendly description for this Podman host. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `hostIdentifier` string, required: Unique identifier for this Podman host, sourced from the host.name OTel resource attribute. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `otelCollectorStatus` string: Connection status of the OTel Collector agent (connected or disconnected). Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `agentVersion` string: Version of the OneUptime Podman agent reporting telemetry, as self-reported via the oneuptime.agent.version resource attribute. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `lastSeenAt` object: When metrics were last received from this host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `containersRunning` number: Cached count of running containers on this host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `containersStopped` number: Cached count of stopped containers on this host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `containersPaused` number: Cached count of paused containers on this host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `osType` string: Operating system type of the Podman host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `osVersion` string: Operating system version of the Podman host. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Edit Podman Host] - `createdByUserId` string, uuid: User ID who created this object (if this object was created by a User). Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `isArchived` boolean: Is this Podman host archived? Archived Podman hosts are hidden from lists but keep collecting telemetry. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `archivedAt` object: When was this Podman host archived? Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `archivedByUserId` string, uuid: User ID who archived this object (if this object was archived by a User). Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `deletedByUserId` string, uuid: User ID who deleted this object (if this object was deleted by a User). Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `labels` object[]: Labels to group and filter by. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `id` string - `retainTelemetryDataForDays` number: Number of days to retain telemetry data for this Podman host. Leave blank to use the project-wide default. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `telemetryRetentionConfig` object: Per-pillar retention overrides for this Podman host (logs by severity, traces by status, metrics, profiles). Unset fields fall back to the Podman host default, then the project's retention settings. Permissions - Create: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Create Podman Host], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `isAiInvestigationEnabled` boolean: When on, OneUptime AI runs read-only commands (docker ps, inspect, logs, stats, events, against the Podman API) on this Podman host, through its Podman AI agent, while investigating incidents and alerts linked to it, and uses their output, with secret values redacted, as evidence. Nothing is ever changed by an investigation. On by default. Anyone who may edit the Podman host can turn it on or off. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `aiRemediationMode` 'Disabled' | 'RequireApproval' | 'Automatic' | 'BypassApproval': Disabled: AI never proposes or runs a change on this Podman host. RequireApproval: AI composes a command plan and a human approves it with one click before anything runs. Automatic: safe changes (SafeWrite) run without a human; a riskier change is proposed for approval unless the Podman host's allowlist names its exact shape. BypassApproval: every change the policy allows — safe AND riskier — runs on its own, except what always needs a human. In EVERY mode: Denied commands never run, commands the policy marks requiresHuman always ask, and the agent itself refuses every write unless it was started with ONEUPTIME_AI_ALLOW_WRITES=true (and then only on the targets ONEUPTIME_AI_WRITE_TARGETS allows, never its protected targets). Anyone who may edit the Podman host can lower the mode; raising it needs Project Owner, Project Admin or Edit AI Rule. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `aiCommandAllowlist` object: Optional JSON array of command patterns that Automatic mode may run on this Podman host without approval even though they are riskier changes. Each pattern is one command line for this Podman host's agent (docker, against the Podman API) and is compared with the command word by word: * stands for exactly one word (a name, an id), never for extra words or flags, and every flag the command uses must be written out in the pattern. At most 50 patterns of at most 500 characters each; a pattern that is not one valid write command for this Podman host is refused. Destructive commands (Denied tier) never run regardless, and a command that always needs a human still asks. Adding a pattern needs Project Owner, Project Admin or Edit AI Rule; anyone who may edit the Podman host can remove patterns or clear the list. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [Project Owner, Project Admin, Project Member, Settings Admin, Settings Member, Edit Podman Host] - `aiAccessLastVerifiedAt` object: When a command from OneUptime AI last succeeded on this Podman host through its Podman AI agent. Set by the server. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `aiAccessLastError` string: The most recent failure OneUptime AI hit while running a command on this Podman host, kept until the next successful command. Set by the server. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] - `aiAccessConfiguredAt` object: When OneUptime AI access to this Podman host was first configured by anyone saving an AI access setting. Set by the server; never cleared, so a Podman AI agent that registers later never overwrites a setting an operator chose. Permissions - Create: [No access - you don't have permission for this operation], Read: [Project Owner, Project Admin, Project Member, Viewer, Settings Admin, Settings Member, Settings Viewer, Read Podman Host], Update: [No access - you don't have permission for this operation] ## Other responses - `400`: Bad request. This response indicates that the request was malformed or contained invalid data. - `401`: Unauthorized. This response indicates that the request requires user authentication. - `402`: Payment Required. This response indicates that the request requires payment or a valid subscription. - `403`: Forbidden. This response indicates that the server understood the request, but refuses to authorize it. - `405`: Project not found. This response indicates that the requested project does not exist or is not accessible. - `408`: Request Timeout. This response indicates that the server timed out waiting for the request. - `415`: Unable to reach server. This response indicates that the server is currently unreachable or down. - `422`: Not authorized. This response indicates that the user does not have permission to access the requested resource. - `500`: Internal Server Error. This response indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. --- [API](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification.md) - [All operations](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification/revisions/ba3307d00304?raw)