Skip to content
🐋Cetacean

Schema Reference

Cetacean API responses include JSON-LD metadata (@context, @id, @type) for self-description. This page documents the vocabulary. The machine-readable context document is available at /api/schema.jsonld.

Types

Each API response includes an @type value identifying the resource kind.

Collection

A paginated list of resources.

EndpointAll list endpointsPropertiesitems, total, limit, offset
Node

A Docker Swarm node (manager or worker).

Endpoint/nodes/{id}Propertiesnode, name, role, state, availability, tasks, services
Service

A Docker Swarm service.

Task

A single running or completed container instance.

Endpoint/tasks/{id}Propertiestask, state, slot, image, hostname
Stack

A group of services deployed together via `com.docker.stack.namespace` labels.

Endpoint/stacks/{name}Propertiesstack, name, tasks
Config

A Docker Swarm config object.

Endpoint/configs/{id}Propertiesconfig, name, services
Secret

A Docker Swarm secret (data always redacted).

Endpoint/secrets/{id}Propertiessecret, name, services
Network

A Docker network.

Endpoint/networks/{id}Propertiesnetwork, name, driver, scope, services
Volume

A Docker volume.

Endpoint/volumes/{name}Propertiesvolume, name, driver, scope, services
Plugin

An installed Docker plugin.

Endpoint/plugins/{name}Propertiesplugin, name
Cluster

Cluster-wide overview with counts and resource totals.

Swarm

Swarm configuration: join tokens, Raft config, CA config.

Endpoint/swarmPropertiesmanagerAddr
ServiceEnv

Service environment variables.

Endpoint/services/{id}/envPropertiesenv
ServicePorts

Service port bindings.

Endpoint/services/{id}/portsPropertiesports
ServiceLabels

Service labels.

Endpoint/services/{id}/labelsPropertieslabels
ServiceResources

Service CPU/memory reservations and limits.

Endpoint/services/{id}/resourcesPropertiesresources
ServicePlacement

Service placement constraints and preferences.

Endpoint/services/{id}/placementPropertiesplacement
ServiceUpdatePolicy

Rolling update configuration for a service.

Endpoint/services/{id}/update-policyPropertiesupdatePolicy
ServiceRollbackPolicy

Rollback configuration for a service.

Endpoint/services/{id}/rollback-policyPropertiesrollbackPolicy
ServiceLogDriver

Log driver configuration for a service.

Endpoint/services/{id}/log-driverPropertieslogDriver
ServiceHealthcheck

Healthcheck configuration for a service.

Endpoint/services/{id}/healthcheckPropertieshealthcheck
ServiceConfigs

Config references attached to a service.

Endpoint/services/{id}/configsPropertiesconfigs
ServiceSecrets

Secret references attached to a service.

Endpoint/services/{id}/secretsPropertiessecrets
ServiceNetworks

Network attachments for a service.

Endpoint/services/{id}/networksPropertiesnetworks
ServiceMounts

Mount configuration for a service.

Endpoint/services/{id}/mountsPropertiesmounts
ServiceMode

Service scheduling mode and replica count.

Endpoint/services/{id}/modePropertiesmode, replicas
ServiceEndpointMode

Service endpoint mode (vip or dnsrr).

Endpoint/services/{id}/endpoint-modePropertiesendpointMode
NodeLabels

Node labels.

Endpoint/nodes/{id}/labelsPropertieslabels
NodeRole

Node role in the swarm.

Endpoint/nodes/{id}/rolePropertiesrole, isLeader, managerCount
ClusterCapacity

Cluster resource capacity: max single-node values and totals.

Endpoint/cluster/capacityPropertiesmaxNodeCPU, maxNodeMemory, totalCPU, totalMemory, nodeCount
SearchResult

Cross-resource search results.

Endpoint/searchPropertiesquery, results, counts, total
RecommendationCollection

Cluster health recommendations from the recommendation engine.

Endpoint/recommendationsPropertiesitems, total, summary, computedAt
HistoryEntry

A resource change event from the history ring buffer or SSE stream.

Endpoint/history, /eventsPropertieskind, action, resourceId, timestamp, name
ServiceRef

A cross-reference to a service (used in config/secret/network/volume detail responses).

EndpointEmbedded in detail responsesPropertiesname
Health

Health check response with build metadata and operations level.

Endpoint/-/healthPropertiesversion, commit, buildDate, operationsLevel
ProblemDetail

An error response following RFC 9457 Problem Details.

EndpointError responsesPropertiestype, title, status, detail, instance, requestId

Properties

Properties are mapped to IRIs via the @context. The urn:cetacean: namespace is the default vocabulary; RFC 9457 problem detail fields use urn:ietf:rfc:9457#.

action

The action performed on a resource (create, update, remove).

IRIurn:cetacean:actionTypeStringUsed onHistoryEntry
aliases

DNS aliases for a service on a given network.

IRIurn:cetacean:aliasesTypeArray of StringUsed onService
availability

The scheduling availability of a node: active, pause, or drain.

IRIurn:cetacean:availabilityTypeStringUsed onNode
buildDate

Build timestamp of the running binary.

IRIurn:cetacean:buildDateTypeStringUsed onHealth
changes@list

Spec changes from the previous service version.

IRIurn:cetacean:changesTypeArrayUsed onService
commit

Git commit SHA of the build.

IRIurn:cetacean:commitTypeStringUsed onHealth
computedAt

Timestamp when recommendations were last computed.

IRIurn:cetacean:computedAtTypeDateTimeUsed onRecommendationCollection
config

The Docker config object.

IRIurn:cetacean:configTypeObjectUsed onConfig
configs@list

Config references attached to a service.

IRIurn:cetacean:configsTypeArrayUsed onServiceConfigs
counts

Result counts per resource type.

IRIurn:cetacean:countsTypeObjectUsed onSearchResult
detail

A human-readable explanation specific to this occurrence (RFC 9457).

IRIurn:ietf:rfc:9457#detailTypeStringUsed onProblemDetail
driver

The driver backing a network or volume (e.g., overlay, local).

IRIurn:cetacean:driverTypeStringUsed onNetwork, Volume
endpointMode

Endpoint mode for a service: vip or dnsrr.

IRIurn:cetacean:endpointModeTypeStringUsed onServiceEndpointMode
env

Environment variables as a key-value map.

IRIurn:cetacean:envTypeObjectUsed onServiceEnv
healthcheck

Container healthcheck configuration.

IRIurn:cetacean:healthcheckTypeObjectUsed onServiceHealthcheck
hostname

Node hostname in a task cross-reference.

IRIurn:cetacean:hostnameTypeStringUsed onTask
image

The container image reference (registry/name:tag@digest).

IRIurn:cetacean:imageTypeStringUsed onService, Task
instance

A URI reference identifying the specific occurrence of the problem (RFC 9457).

IRIurn:ietf:rfc:9457#instanceTypeURIUsed onProblemDetail
integrations@list

Detected third-party integrations for a service.

IRIurn:cetacean:integrationsTypeArrayUsed onService
isLeader

Whether this manager node is the Raft leader.

IRIurn:cetacean:isLeaderTypeBooleanUsed onNodeRole
items@set

The set of resources in a collection response.

IRIurn:cetacean:itemsTypeArrayUsed onCollection, RecommendationCollection
kind

The resource kind for history and SSE events (e.g., service, node).

IRIurn:cetacean:kindTypeStringUsed onHistoryEntry
labels

Labels as a key-value map.

IRIurn:cetacean:labelsTypeObjectUsed onServiceLabels, NodeLabels
limit

Page size limit for a collection response.

IRIurn:cetacean:limitTypeIntegerUsed onCollection
logDriver

Log driver name and options.

IRIurn:cetacean:logDriverTypeObjectUsed onServiceLogDriver
managerAddr

Manager node address for remote Docker API access.

IRIurn:cetacean:managerAddrTypeStringUsed onSwarm
managerCount

Total number of manager nodes in the swarm.

IRIurn:cetacean:managerCountTypeIntegerUsed onNodeRole
maxNodeCPU

CPU capacity (nanoCPUs) of the largest node in the cluster.

IRIurn:cetacean:maxNodeCPUTypeIntegerUsed onClusterCapacity
maxNodeMemory

Memory capacity (bytes) of the largest node in the cluster.

IRIurn:cetacean:maxNodeMemoryTypeIntegerUsed onClusterCapacity
mode

The scheduling mode of a service: replicated or global.

IRIurn:cetacean:modeTypeStringUsed onService, ServiceMode
mounts@list

Mount configuration attached to a service.

IRIurn:cetacean:mountsTypeArrayUsed onServiceMounts
name

The human-readable name of a resource. For nodes this is the hostname; for services, configs, secrets, networks, and volumes it is the Docker object name.

IRIurn:cetacean:nameTypeStringUsed onNode, Service, Stack, Config, Secret, Network, Volume, ServiceRef
network

The Docker network object.

IRIurn:cetacean:networkTypeObjectUsed onNetwork
networks@list

The networks a service is attached to.

IRIurn:cetacean:networksTypeArray of NetworkAttachmentUsed onService, ServiceNetworks
node

The Docker node object.

IRIurn:cetacean:nodeTypeObjectUsed onNode
nodeCount

Number of nodes in the cluster.

IRIurn:cetacean:nodeCountTypeIntegerUsed onCluster, ClusterCapacity
nodesDown

Number of nodes in down state.

IRIurn:cetacean:nodesDownTypeIntegerUsed onCluster
nodesDraining

Number of nodes in drain state.

IRIurn:cetacean:nodesDrainingTypeIntegerUsed onCluster
nodesReady

Number of nodes in ready state.

IRIurn:cetacean:nodesReadyTypeIntegerUsed onCluster
offset

Page offset for a collection response.

IRIurn:cetacean:offsetTypeIntegerUsed onCollection
operationsLevel

Current operations level (0=read-only, 1=operational, 2=configuration, 3=impactful).

IRIurn:cetacean:operationsLevelTypeIntegerUsed onHealth
placement

Placement constraints and preferences for a service.

IRIurn:cetacean:placementTypeObjectUsed onServicePlacement
plugin

The Docker plugin object.

IRIurn:cetacean:pluginTypeObjectUsed onPlugin
ports@list

Published port bindings for a service, ordered by target port.

IRIurn:cetacean:portsTypeArray of PortConfigUsed onService, ServicePorts
prometheusConfigured

Whether a Prometheus instance is configured.

IRIurn:cetacean:prometheusConfiguredTypeBooleanUsed onCluster
query

The search query string.

IRIurn:cetacean:queryTypeStringUsed onSearchResult
replicas

The configured number of replicas for a replicated service.

IRIurn:cetacean:replicasTypeIntegerUsed onService, ServiceMode
requestId

Unique request identifier for error correlation.

IRIurn:cetacean:requestIdTypeStringUsed onProblemDetail
reservedCPU

Total reserved CPU (nanoCPUs) across all services.

IRIurn:cetacean:reservedCPUTypeIntegerUsed onCluster
reservedMemory

Total reserved memory (bytes) across all services.

IRIurn:cetacean:reservedMemoryTypeIntegerUsed onCluster
resourceId

The ID of the affected resource.

IRIurn:cetacean:resourceIdTypeStringUsed onHistoryEntry
resources

CPU/memory reservations and limits for a service.

IRIurn:cetacean:resourcesTypeObjectUsed onServiceResources
results

Search results grouped by resource type.

IRIurn:cetacean:resultsTypeObjectUsed onSearchResult
role

The role of a node in the swarm: manager or worker.

IRIurn:cetacean:roleTypeStringUsed onNode, NodeRole
rollbackPolicy

Rollback configuration for a service.

IRIurn:cetacean:rollbackPolicyTypeObjectUsed onServiceRollbackPolicy
scope

The scope of a network or volume: swarm or local.

IRIurn:cetacean:scopeTypeStringUsed onNetwork, Volume
secret

The Docker secret object (data always redacted).

IRIurn:cetacean:secretTypeObjectUsed onSecret
secrets@list

Secret references attached to a service.

IRIurn:cetacean:secretsTypeArrayUsed onServiceSecrets
service

The Docker service object.

IRIurn:cetacean:serviceTypeObjectUsed onService
serviceCount

Number of services in the cluster.

IRIurn:cetacean:serviceCountTypeIntegerUsed onCluster
services@list

Cross-referenced services using this resource.

IRIurn:cetacean:servicesTypeArray of ServiceRefUsed onConfig, Secret, Network, Volume
servicesConverged

Number of services with all tasks running.

IRIurn:cetacean:servicesConvergedTypeIntegerUsed onCluster
servicesDegraded

Number of services with fewer tasks than desired.

IRIurn:cetacean:servicesDegradedTypeIntegerUsed onCluster
slot

The slot number of a task within a replicated service. Each replica occupies a unique slot.

IRIurn:cetacean:slotTypeIntegerUsed onTask
stack

The stack detail with member resources.

IRIurn:cetacean:stackTypeObjectUsed onStack
stackCount

Number of stacks in the cluster.

IRIurn:cetacean:stackCountTypeIntegerUsed onCluster
state

The current state of a resource. For nodes: ready, down, or unknown. For tasks: running, failed, complete, etc. For services: a derived state based on running/desired task counts.

IRIurn:cetacean:stateTypeStringUsed onNode, Service, Task
status

The HTTP status code for the problem (RFC 9457).

IRIurn:ietf:rfc:9457#statusTypeIntegerUsed onProblemDetail
summary

Severity summary (critical/warning/info counts).

IRIurn:cetacean:summaryTypeObjectUsed onRecommendationCollection
task

The Docker task object, enriched with ServiceName and NodeHostname.

IRIurn:cetacean:taskTypeObjectUsed onTask
taskCount

Number of tasks in the cluster.

IRIurn:cetacean:taskCountTypeIntegerUsed onCluster
tasks@list

The list of tasks belonging to a service or running on a node.

IRIurn:cetacean:tasksTypeArray of TaskUsed onService, Node, Stack
tasksByState

Task counts grouped by state.

IRIurn:cetacean:tasksByStateTypeObjectUsed onCluster
timestamp

When the event occurred.

IRIurn:cetacean:timestampTypeDateTimeUsed onHistoryEntry
title

A short human-readable summary of the problem type (RFC 9457).

IRIurn:ietf:rfc:9457#titleTypeStringUsed onProblemDetail
total

Total count of items.

IRIurn:cetacean:totalTypeIntegerUsed onCollection, SearchResult, RecommendationCollection
totalCPU

Total cluster CPU capacity (nanoCPUs).

IRIurn:cetacean:totalCPUTypeIntegerUsed onCluster, ClusterCapacity
totalMemory

Total cluster memory capacity (bytes).

IRIurn:cetacean:totalMemoryTypeIntegerUsed onCluster, ClusterCapacity
type

A URI reference identifying the problem type (RFC 9457).

IRIurn:ietf:rfc:9457#typeTypeURIUsed onProblemDetail
updatePolicy

Rolling update configuration for a service.

IRIurn:cetacean:updatePolicyTypeObjectUsed onServiceUpdatePolicy
updateStatus

The status of a rolling update for a service, if one is in progress.

IRIurn:cetacean:updateStatusTypeUpdateStatusUsed onService
version

Software version string.

IRIurn:cetacean:versionTypeStringUsed onHealth
volume

The Docker volume object.

IRIurn:cetacean:volumeTypeObjectUsed onVolume