---
title: "Register Fleet Spec"
method: POST
path: "/fleet/specs"
---

# Register Fleet Spec

`POST /fleet/specs`

## Request

- Base URL: `https://api-docs.session-exchange.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.session-exchange.com/fleet/specs`
- Auth: none declared

## Request body

- FleetSpecRequest: A satellite service's declarative run-spec (specs/fleet-spec/v0.1; v0.2 adds `kind: "router"`, `host`, `image_digest` and the `router{}` block — all optional and omitted from the stored record when unset, so v0.1 records are unchanged). The collector owns these so a removed fleet is rebuildable from the main service; secrets are refs only (see SecretRef).
  - `name` string, required
  - `kind` 'container' | 'pool' | 'oauth_holder' | 'router'
  - `host` string, nullable
  - `image_digest` string, nullable
  - `router` RouterBlock: fleet-spec v0.2 `router{}` block (router-fleet PLAN C1). Required iff `kind == "router"`; the cross-field rules (env allow-list, secret env_keys) live in `collector/router_registry.py`.
    - `id` string, required
    - `role` 'fleet' | 'customer' | 'internal' | 'staging', required
    - `env` 'prod' | 'staging'
    - `channel` 'stable' | 'canary'
    - `pool` string, nullable
    - `region` string, nullable
    - `producer` string, required
    - `status` 'provisioning' | 'active' | 'draining' | 'disabled' | 'retired'
    - `weight` integer
    - `edge` RouterEdge: fleet-spec v0.2 `router.edge` — how the router is reached (02 §P1).
      - `unique_host` string, nullable
      - `aliases` string[]
      - `meta` string[]
      - `public_ips` string[]
      - `type` string, nullable
      - `trusted_proxies` string[]
      - `tls_mode` string, nullable
    - `owner_operator` string, nullable
    - `gate_profile` string, nullable
    - `expected` RouterExpected: `router.expected` — the posture the router MUST report (heartbeat drift input).
      - `posture` object
    - `expect` RouterExpect: `router.expect` — fingerprints written by the deploy tool (03 §3.3 step 6).
      - `env_names_sha256` string, nullable
      - `config_fingerprint` string, nullable
      - `build` string, nullable
  - `image` string, required
  - `desired` 'running' | 'stopped'
  - `build` object, nullable
  - `entrypoint` string[], nullable
  - `cmd` string[]
  - `user` string, nullable
  - `hostname` string, nullable
  - `network` string, nullable
  - `restart` string
  - `env` object
  - `secret_refs` SecretRef[]
    - `env_key` string, required
    - `name` string, required
  - `volumes` string[]
  - `ports` string[]
  - `depends_on` string[]
  - `replicas` integer, nullable
  - `holder` string, nullable
  - `env_tokens` object
  - `description` string

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/session-exchange/apis/a4sx.md) · [All operations](https://skmtc.dev/session-exchange/apis/a4sx/llms.txt) · [OpenAPI document](https://skmtc.dev/session-exchange/apis/a4sx/revisions/abaefc33dfc7?raw)