{ "openapi": "3.0.3", "info": { "title": "Collector Fleet API", "version": "1.0.0", "description": "The collector fleet control plane \u2014 enrollment, dispatch, tokens, and releases." }, "servers": [ { "url": "https://versus-demo.com" } ], "paths": { "/api/agent-releases/": { "get": { "operationId": "agent_releases_list", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "parameters": [ { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } } ], "tags": [ "agent-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCollectorReleaseList" } } }, "description": "" } }, "summary": "List agent releases" }, "post": { "operationId": "agent_releases_create", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "tags": [ "agent-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Create agent release" } }, "/api/agent-releases/{id}/": { "get": { "operationId": "agent_releases_retrieve", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "agent-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Retrieve agent release" }, "put": { "operationId": "agent_releases_update", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "agent-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Update agent release" }, "patch": { "operationId": "agent_releases_partial_update", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "agent-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Update agent release" }, "delete": { "operationId": "agent_releases_destroy", "description": "Catalog of published collector-agent versions. Publishing a release\nwith is_latest=True lights up 'update available' across the fleet; uploading\na per-OS/arch binary makes it applicable (a signed manifest is served for it).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "agent-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "204": { "description": "No response body" } }, "summary": "Delete agent release" } }, "/api/agent-releases/{id}/artifact/": { "post": { "operationId": "agent_releases_artifact_create", "description": "Attach a per-OS/arch collector binary to this release. Its bytes are\nstored and its sha256 recorded; the signed manifest authenticates it.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "agent-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Artifact: agent release" } }, "/api/collector-releases/": { "get": { "operationId": "collector_releases_list", "parameters": [ { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } } ], "tags": [ "collector-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorRelease" } } } }, "description": "" } }, "summary": "List collector releases" }, "post": { "operationId": "collector_releases_create", "tags": [ "collector-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Create collector release" } }, "/api/collector-releases/{id}/": { "get": { "operationId": "collector_releases_retrieve", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Retrieve collector release" }, "put": { "operationId": "collector_releases_update", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Update collector release" }, "patch": { "operationId": "collector_releases_partial_update", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedCollectorReleaseRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Update collector release" }, "delete": { "operationId": "collector_releases_destroy", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "204": { "description": "No response body" } }, "summary": "Delete collector release" } }, "/api/collector-releases/{id}/download/": { "get": { "operationId": "collector_releases_download_retrieve", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Download: collector release" } }, "/api/collector-releases/{id}/promote/": { "post": { "operationId": "collector_releases_promote_create", "description": "Promote this downloadable bundle to an auto-update release: extract the\nraw collector binary and register it (in collector_cp) as a signed-manifest\nartifact, so fielded collectors can self-update to this version via the\nCollector Management \u2192 Apply flow. Marks the version as the latest target.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this collector release.", "required": true } ], "tags": [ "collector-releases" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorReleaseRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRelease" } } }, "description": "" } }, "summary": "Promote: collector release" } }, "/api/collector-tokens/": { "get": { "operationId": "collector_tokens_list", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } } ], "tags": [ "collector-tokens" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCollectorEnrollTokenList" } } }, "description": "" } }, "summary": "List collector tokens" }, "post": { "operationId": "collector_tokens_create", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "tags": [ "collector-tokens" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollToken" } } }, "description": "" } }, "summary": "Create collector token" } }, "/api/collector-tokens/{id}/": { "get": { "operationId": "collector_tokens_retrieve", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this collector enroll token.", "required": true } ], "tags": [ "collector-tokens" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollToken" } } }, "description": "" } }, "summary": "Retrieve collector token" }, "put": { "operationId": "collector_tokens_update", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this collector enroll token.", "required": true } ], "tags": [ "collector-tokens" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollToken" } } }, "description": "" } }, "summary": "Update collector token" }, "patch": { "operationId": "collector_tokens_partial_update", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this collector enroll token.", "required": true } ], "tags": [ "collector-tokens" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedCollectorEnrollTokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedCollectorEnrollTokenRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedCollectorEnrollTokenRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollToken" } } }, "description": "" } }, "summary": "Update collector token" }, "delete": { "operationId": "collector_tokens_destroy", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this collector enroll token.", "required": true } ], "tags": [ "collector-tokens" ], "security": [ { "jwtAuth": [] } ], "responses": { "204": { "description": "No response body" } }, "summary": "Delete collector token" } }, "/api/collector-tokens/{id}/revoke/": { "post": { "operationId": "collector_tokens_revoke_create", "description": "spec \u00a710.1: POST /collector-tokens. The plaintext token is only ever\npresent in the create response \u2014 token_hash is one-way, so it can't be\nrecovered afterward (matches \"shown once at creation\" from \u00a72.1).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this collector enroll token.", "required": true } ], "tags": [ "collector-tokens" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorEnrollTokenRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorEnrollToken" } } }, "description": "" } }, "summary": "Revoke: collector token" } }, "/api/collector/v1/artifact/{artifact_id}": { "get": { "operationId": "collector_v1_artifact_retrieve", "description": "GET /api/collector/v1/artifact/ \u2014 stream a collector binary. Integrity\nis guaranteed by the sha256 in the signed manifest, so this needn't be auth'd.", "parameters": [ { "in": "path", "name": "artifact_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "collector" ], "security": [ {} ], "responses": { "200": { "description": "No response body" } }, "summary": "Retrieve artifact" } }, "/api/collector/v1/enroll": { "post": { "operationId": "collector_v1_enroll_create", "description": "POST /api/collector/v1/enroll \u2014 spec \u00a72.2. Public (token-authenticated,\nnot JWT/session) since a brand-new collector has no other credential yet.", "tags": [ "collector" ], "security": [ {} ], "responses": { "200": { "description": "No response body" } }, "summary": "Create enroll" } }, "/api/collector/v1/manifest": { "get": { "operationId": "collector_v1_manifest_retrieve", "description": "GET /api/collector/v1/manifest?version=&os=&arch= \u2014 a signed update\nmanifest (\u00a78.4) for the collector's supervisor. version omitted \u21d2 latest.", "tags": [ "collector" ], "security": [ {} ], "responses": { "200": { "description": "No response body" } }, "summary": "List manifests" } }, "/api/collectors/": { "get": { "operationId": "collectors_list", "description": "spec \u00a710.1: GET /collectors, GET /collectors/{id}, plus\ndrain/undrain/revoke/probe actions. drain/undrain set a flag the\ngateway's existing DB-polling loop picks up (see gateway.py) since the\nadmin API and the gateway are separate processes in this deployment \u2014\nthere's no in-process channel to push a Drain frame synchronously.", "parameters": [ { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } } ], "tags": [ "collectors" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCollectorList" } } }, "description": "" } }, "summary": "List collectors" } }, "/api/collectors/{collector_id}/": { "get": { "operationId": "collectors_retrieve", "description": "spec \u00a710.1: GET /collectors, GET /collectors/{id}, plus\ndrain/undrain/revoke/probe actions. drain/undrain set a flag the\ngateway's existing DB-polling loop picks up (see gateway.py) since the\nadmin API and the gateway are separate processes in this deployment \u2014\nthere's no in-process channel to push a Drain frame synchronously.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Retrieve collector" } }, "/api/collectors/{collector_id}/apply-update/": { "post": { "operationId": "collectors_apply_update_create", "description": "Approve an agent upgrade for this collector. Sets target_version \u2014 the\nlong-poll claim then advertises it and the collector's supervisor applies\nthe signed release with a health-check + automatic rollback. Defaults to\nthe latest published release; an explicit version may be supplied.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Apply update: collector" } }, "/api/collectors/{collector_id}/clear-update/": { "post": { "operationId": "collectors_clear_update_create", "description": "Cancel a pending/approved upgrade target for this collector.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Clear update: collector" } }, "/api/collectors/{collector_id}/delete/": { "post": { "operationId": "collectors_delete_create", "description": "Permanently remove a collector row. Cascades its liveness/sessions/\ncapabilities/seeds/jobs; dispatch history is kept but unlinked (SET_NULL).\nGuarded: a currently-connected collector must be revoked first, so a\nworking collector can't be deleted out from under active work by mistake.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Delete: collector" }, "delete": { "operationId": "collectors_delete_destroy", "description": "Permanently remove a collector row. Cascades its liveness/sessions/\ncapabilities/seeds/jobs; dispatch history is kept but unlinked (SET_NULL).\nGuarded: a currently-connected collector must be revoked first, so a\nworking collector can't be deleted out from under active work by mistake.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "security": [ { "jwtAuth": [] } ], "responses": { "204": { "description": "No response body" } }, "summary": "Delete: collector" } }, "/api/collectors/{collector_id}/drain/": { "post": { "operationId": "collectors_drain_create", "description": "spec \u00a77.4/\u00a710.1: stop routing new tasks to this collector and\nsignal it via the Drain frame. Session state flips to 'draining'\nimmediately (the router's filter already excludes it from new\ncandidates); the gateway process delivers the actual Drain frame\non its next poll tick.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Drain: collector" } }, "/api/collectors/{collector_id}/probe/": { "post": { "operationId": "collectors_probe_create", "description": "spec \u00a710.1: a lightweight connectivity/health check \u2014 reports\nthe live session's own heartbeat freshness rather than routing a\nsynthetic task (Phase 0 scope; a real active-probe task is Phase 1).", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Probe: collector" } }, "/api/collectors/{collector_id}/revoke/": { "post": { "operationId": "collectors_revoke_create", "description": "spec \u00a710.1: GET /collectors, GET /collectors/{id}, plus\ndrain/undrain/revoke/probe actions. drain/undrain set a flag the\ngateway's existing DB-polling loop picks up (see gateway.py) since the\nadmin API and the gateway are separate processes in this deployment \u2014\nthere's no in-process channel to push a Drain frame synchronously.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Revoke: collector" } }, "/api/collectors/{collector_id}/set-data-mask/": { "post": { "operationId": "collectors_set_data_mask_create", "description": "Toggle Data Mask mode for this collector. When enabled, the collector\npseudonymizes IP addresses and object names in every result it reports,\non the collector, before the payload reaches the gateway \u2014 so a client's\nlive environment can be demonstrated through Versus without exposing real\ndata. Unlike vault mode, this needs no restart: the flag rides the\nlong-poll claim response and the agent applies it on the next claim (see\nversus-agent's claim `data_mask` handling). Persisting it on the row is\nall that's required; the claim builder reads it live.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Set data mask: collector" } }, "/api/collectors/{collector_id}/set-vault-mode/": { "post": { "operationId": "collectors_set_vault_mode_create", "description": "Changes which credential-resolution mode this collector runs.\nMode C points at an existing Vault integration (VaultMount,\ndriver_type='hashicorp') rather than raw connection details \u2014\nthe admin picks one they've already configured under Secret\nVault. Persists the choice on the Collector row (so it's what a\nfresh enrollment or restart picks up regardless of live-session\nstate), and \u2014 if a session is currently live \u2014 flags it for\ndelivery via the same DB-flag/poll-loop pattern as drain. The\ncollector itself applies the change by restarting (a live\nprocess can't safely swap its credential resolver mid-dispatch)\n\u2014 see versus-agent's OnVaultConfig handler.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Set vault mode: collector" } }, "/api/collectors/{collector_id}/undrain/": { "post": { "operationId": "collectors_undrain_create", "description": "spec \u00a710.1: GET /collectors, GET /collectors/{id}, plus\ndrain/undrain/revoke/probe actions. drain/undrain set a flag the\ngateway's existing DB-polling loop picks up (see gateway.py) since the\nadmin API and the gateway are separate processes in this deployment \u2014\nthere's no in-process channel to push a Drain frame synchronously.", "parameters": [ { "in": "path", "name": "collector_id", "schema": { "type": "string" }, "description": "A unique value identifying this collector.", "required": true } ], "tags": [ "collectors" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectorRequest" } } }, "required": true }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collector" } } }, "description": "" } }, "summary": "Undrain: collector" } }, "/api/control-plane/break-glass/": { "get": { "operationId": "control_plane_break_glass_retrieve", "description": "Plain APIViews rather than a DRF router ViewSet (apps.tenants.\nbreakglass's request/approve/deny/consume actions are bespoke, not\nCRUD) \u2014 same shape as apps/vault/reveal.py's reveal-request flow.", "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "summary": "List break glasss" }, "post": { "operationId": "control_plane_break_glass_create", "description": "Plain APIViews rather than a DRF router ViewSet (apps.tenants.\nbreakglass's request/approve/deny/consume actions are bespoke, not\nCRUD) \u2014 same shape as apps/vault/reveal.py's reveal-request flow.", "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "summary": "Create break glass" } }, "/api/control-plane/break-glass/{id}/approve/": { "post": { "operationId": "control_plane_break_glass_approve_create", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "summary": "Approve: break glass" } }, "/api/control-plane/break-glass/{id}/consume/": { "post": { "operationId": "control_plane_break_glass_consume_create", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "summary": "Consume: break glass" } }, "/api/control-plane/break-glass/{id}/deny/": { "post": { "operationId": "control_plane_break_glass_deny_create", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "summary": "Deny: break glass" } }, "/api/control-plane/eula-acceptances/": { "get": { "operationId": "control_plane_eula_acceptances_list", "description": "Control Plane EULA acceptance ledger (spec \u00a78) \u2014 read-only.", "parameters": [ { "in": "query", "name": "eula_version", "schema": { "type": "string", "format": "uuid" } }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "in": "query", "name": "tenant", "schema": { "type": "string", "format": "uuid" } } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEulaAcceptanceList" } } }, "description": "" } }, "summary": "List eula acceptances" } }, "/api/control-plane/eula-acceptances/{id}/": { "get": { "operationId": "control_plane_eula_acceptances_retrieve", "description": "Control Plane EULA acceptance ledger (spec \u00a78) \u2014 read-only.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this eula acceptance.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EulaAcceptance" } } }, "description": "" } }, "summary": "Retrieve eula acceptance" } }, "/api/control-plane/requests/": { "get": { "operationId": "control_plane_requests_list", "description": "Control Plane inbox (spec \u00a78) \u2014 approve triggers the provisioning\nworkflow synchronously (see apps.tenants.provisioning); reject just\nrecords a reason. Both are terminal \u2014 a request can't be re-approved\nor re-rejected once decided.", "parameters": [ { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "approved", "pending", "rejected" ] }, "description": "* `pending` - Pending\n* `approved` - Approved\n* `rejected` - Rejected" } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTenantRequestList" } } }, "description": "" } }, "summary": "List requests" } }, "/api/control-plane/requests/{id}/": { "get": { "operationId": "control_plane_requests_retrieve", "description": "Control Plane inbox (spec \u00a78) \u2014 approve triggers the provisioning\nworkflow synchronously (see apps.tenants.provisioning); reject just\nrecords a reason. Both are terminal \u2014 a request can't be re-approved\nor re-rejected once decided.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant request.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } }, "description": "" } }, "summary": "Retrieve request" } }, "/api/control-plane/requests/{id}/approve/": { "post": { "operationId": "control_plane_requests_approve_create", "description": "Control Plane inbox (spec \u00a78) \u2014 approve triggers the provisioning\nworkflow synchronously (see apps.tenants.provisioning); reject just\nrecords a reason. Both are terminal \u2014 a request can't be re-approved\nor re-rejected once decided.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant request.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } }, "description": "" } }, "summary": "Approve: request" } }, "/api/control-plane/requests/{id}/reject/": { "post": { "operationId": "control_plane_requests_reject_create", "description": "Control Plane inbox (spec \u00a78) \u2014 approve triggers the provisioning\nworkflow synchronously (see apps.tenants.provisioning); reject just\nrecords a reason. Both are terminal \u2014 a request can't be re-approved\nor re-rejected once decided.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant request.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } }, "description": "" } }, "summary": "Reject: request" } }, "/api/control-plane/requests/{id}/revoke/": { "post": { "operationId": "control_plane_requests_revoke_create", "description": "Deprovision an already-approved request: reverse its provisioning run\n\u2014 deleting the tenant, its Zitadel org, and any invitations \u2014 then mark\nthe request rejected so the org code is free for a corrected request.\nReuses the same reverse() compensation the failure path runs, so nothing\nnew can leak that approval didn't already know how to clean up.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant request.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } }, "description": "" } }, "summary": "Revoke: request" } }, "/api/control-plane/tenants/": { "get": { "operationId": "control_plane_tenants_list", "description": "Control Plane tenant registry (spec \u00a78) \u2014 no create/delete here;\ntenants only ever come from the provisioning workflow.", "parameters": [ { "in": "query", "name": "kind", "schema": { "type": "string", "enum": [ "admin", "demo", "production" ] }, "description": "* `admin` - Admin\n* `demo` - Demo\n* `production` - Production" }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "active", "deleted", "expired", "provisioning", "purging", "suspended" ] }, "description": "* `provisioning` - Provisioning\n* `active` - Active\n* `suspended` - Suspended\n* `expired` - Expired\n* `purging` - Purging\n* `deleted` - Deleted" } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTenantList" } } }, "description": "" } }, "summary": "List tenants" } }, "/api/control-plane/tenants/{id}/": { "get": { "operationId": "control_plane_tenants_retrieve", "description": "Control Plane tenant registry (spec \u00a78) \u2014 no create/delete here;\ntenants only ever come from the provisioning workflow.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Retrieve tenant" } }, "/api/control-plane/tenants/{id}/entitlement/": { "get": { "operationId": "control_plane_tenants_entitlement_retrieve", "description": "GET the tenant's entitlement, or POST to set/update it (+ audit).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Entitlement: tenant" }, "post": { "operationId": "control_plane_tenants_entitlement_create", "description": "GET the tenant's entitlement, or POST to set/update it (+ audit).", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Entitlement: tenant" } }, "/api/control-plane/tenants/{id}/extend-expiry/": { "post": { "operationId": "control_plane_tenants_extend_expiry_create", "description": "The safety valve ahead of the daily crypto-shred sweep\n(apps.tenants.expiry) \u2014 push expires_at out before the tenant\ngets caught by it. Also lets an admin give a never-expiring\n(expires_at=None) tenant a TTL for the first time.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Extend expiry: tenant" } }, "/api/control-plane/tenants/{id}/resume/": { "post": { "operationId": "control_plane_tenants_resume_create", "description": "Control Plane tenant registry (spec \u00a78) \u2014 no create/delete here;\ntenants only ever come from the provisioning workflow.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Resume: tenant" } }, "/api/control-plane/tenants/{id}/rotate-kek/": { "post": { "operationId": "control_plane_tenants_rotate_kek_create", "description": "Control Plane tenant registry (spec \u00a78) \u2014 no create/delete here;\ntenants only ever come from the provisioning workflow.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Rotate kek: tenant" } }, "/api/control-plane/tenants/{id}/suspend/": { "post": { "operationId": "control_plane_tenants_suspend_create", "description": "Control Plane tenant registry (spec \u00a78) \u2014 no create/delete here;\ntenants only ever come from the provisioning workflow.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this tenant.", "required": true } ], "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Suspend: tenant" } }, "/api/control-plane/tenants/provision/": { "post": { "operationId": "control_plane_tenants_provision_create", "description": "Direct production-tenant creation (VS-SPEC-SAAS-LICENSING-001) \u2014 no\nrequest/approve. Provisions the tenant (Zitadel org \u2192 admin \u2192 native IdP\ninvite, same workflow as approve) and stamps its module entitlement.", "tags": [ "control-plane" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TenantRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TenantRequest" } } } }, "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "" } }, "summary": "Create provision" } }, "/api/dispatches/": { "get": { "operationId": "dispatches_list", "description": "spec \u00a710.1: GET /dispatches \u2014 the indeterminate queue is just this\nlist filtered to state=indeterminate, a first-class operator view per\nspec \u00a710.3.", "parameters": [ { "in": "query", "name": "collector", "schema": { "type": "string" } }, { "in": "query", "name": "op_class", "schema": { "type": "string", "enum": [ "mutate_reconcilable", "mutate_terminal", "read" ] }, "description": "* `read` - Read\n* `mutate_reconcilable` - Mutate (Reconcilable)\n* `mutate_terminal` - Mutate (Terminal)" }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "in": "query", "name": "provider", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "A search term.", "schema": { "type": "string" } }, { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "cancelled", "dispatched", "expired", "failed", "indeterminate", "leased", "queued", "reconciling", "routed", "running", "success", "unknown" ] }, "description": "* `queued` - Queued\n* `routed` - Routed\n* `leased` - Leased\n* `dispatched` - Dispatched\n* `running` - Running\n* `success` - Success\n* `failed` - Failed\n* `unknown` - Unknown\n* `reconciling` - Reconciling\n* `indeterminate` - Indeterminate\n* `expired` - Expired\n* `cancelled` - Cancelled" } ], "tags": [ "dispatches" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTaskDispatchList" } } }, "description": "" } }, "summary": "List dispatchs" } }, "/api/dispatches/{id}/": { "get": { "operationId": "dispatches_retrieve", "description": "spec \u00a710.1: GET /dispatches \u2014 the indeterminate queue is just this\nlist filtered to state=indeterminate, a first-class operator view per\nspec \u00a710.3.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this task dispatch.", "required": true } ], "tags": [ "dispatches" ], "security": [ { "jwtAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDispatch" } } }, "description": "" } }, "summary": "Retrieve dispatch" } } }, "components": { "schemas": { "PaginatedCollectorEnrollTokenList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorEnrollToken" } } } }, "CollectorRequest": { "type": "object", "properties": { "collector_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "site": { "type": "integer" }, "hostname": { "type": "string", "maxLength": 255 }, "os": { "type": "string", "maxLength": 50 }, "arch": { "type": "string", "maxLength": 20 }, "version": { "type": "string", "maxLength": 50 }, "target_version": { "type": "string", "maxLength": 50 }, "update_requested_at": { "type": "string", "format": "date-time", "nullable": true }, "fips_requested": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/CollectorStatusEnum" }, "cert_serial": { "type": "string", "maxLength": 100 }, "cert_fingerprint_sha256": { "type": "string", "maxLength": 64 }, "cert_not_after": { "type": "string", "format": "date-time", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_reason": { "type": "string" }, "vault_mode": { "$ref": "#/components/schemas/VaultModeEnum" }, "vault_mount": { "type": "integer", "nullable": true }, "external_vault": { "type": "string", "format": "uuid", "nullable": true }, "data_mask_enabled": { "type": "boolean" } }, "required": [ "collector_id", "site" ] }, "TaskDispatchStateEnum": { "enum": [ "queued", "routed", "leased", "dispatched", "running", "success", "failed", "unknown", "reconciling", "indeterminate", "expired", "cancelled" ], "type": "string", "description": "* `queued` - Queued\n* `routed` - Routed\n* `leased` - Leased\n* `dispatched` - Dispatched\n* `running` - Running\n* `success` - Success\n* `failed` - Failed\n* `unknown` - Unknown\n* `reconciling` - Reconciling\n* `indeterminate` - Indeterminate\n* `expired` - Expired\n* `cancelled` - Cancelled" }, "TenantRequest": { "type": "object", "description": "Control Plane inbox view \u2014 read (+ reviewed_by/at set by the\napprove/reject actions, never directly writable here).", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "org_name": { "type": "string", "readOnly": true }, "org_code_requested": { "type": "string", "readOnly": true }, "requester_name": { "type": "string", "readOnly": true }, "requester_email": { "type": "string", "format": "email", "readOnly": true }, "requester_title": { "type": "string", "readOnly": true }, "country": { "type": "string", "readOnly": true }, "use_case": { "type": "string", "readOnly": true }, "invitee_emails": { "readOnly": true }, "state": { "allOf": [ { "$ref": "#/components/schemas/TenantStateEnum" } ], "readOnly": true }, "rejected_reason": { "type": "string", "readOnly": true }, "reviewed_by": { "type": "integer", "readOnly": true, "nullable": true }, "reviewed_by_username": { "type": "string", "readOnly": true, "default": "" }, "reviewed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "workflow_run_id": { "type": "integer", "readOnly": true, "nullable": true }, "tenant": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "country", "created_at", "id", "invitee_emails", "org_code_requested", "org_name", "rejected_reason", "requester_email", "requester_name", "requester_title", "reviewed_at", "reviewed_by", "reviewed_by_username", "state", "tenant", "use_case", "workflow_run_id" ] }, "TenantKindEnum": { "enum": [ "admin", "demo", "production" ], "type": "string", "description": "* `admin` - Admin\n* `demo` - Demo\n* `production` - Production" }, "CollectorStatusEnum": { "enum": [ "pending", "active", "revoked", "expired" ], "type": "string", "description": "* `pending` - Pending Approval\n* `active` - Active\n* `revoked` - Revoked\n* `expired` - Expired" }, "CollectorRelease": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "version": { "type": "string", "maxLength": 50 }, "channel": { "$ref": "#/components/schemas/ChannelEnum" }, "is_latest": { "type": "boolean" }, "security": { "type": "boolean" }, "min_version": { "type": "string", "maxLength": 50 }, "notes": { "type": "string" }, "manifest_url": { "type": "string", "maxLength": 500 }, "published_at": { "type": "string", "format": "date-time", "readOnly": true }, "published_by": { "type": "string", "readOnly": true } }, "required": [ "id", "published_at", "published_by", "version" ] }, "EulaAcceptance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "tenant": { "type": "string", "format": "uuid" }, "user": { "type": "integer" }, "eula_version": { "type": "string", "format": "uuid" }, "accepted_at": { "type": "string", "format": "date-time", "readOnly": true }, "typed_name": { "type": "string", "maxLength": 200 } }, "required": [ "accepted_at", "eula_version", "id", "tenant", "typed_name", "user" ] }, "Tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "org_code": { "type": "string", "readOnly": true, "pattern": "^[-a-zA-Z0-9_]+$" }, "org_name": { "type": "string", "readOnly": true }, "kind": { "allOf": [ { "$ref": "#/components/schemas/TenantKindEnum" } ], "readOnly": true }, "state": { "$ref": "#/components/schemas/TenantStateEnum" }, "holds_real_credentials": { "type": "boolean", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "member_count": { "type": "integer", "readOnly": true }, "kek_version": { "type": "string", "readOnly": true }, "kek_rotated_at": { "type": "string", "readOnly": true }, "entitlement": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "entitlement", "holds_real_credentials", "id", "kek_rotated_at", "kek_version", "kind", "member_count", "org_code", "org_name" ] }, "CollectorCapability": { "type": "object", "properties": { "provider": { "type": "string", "maxLength": 100 }, "driver_version": { "type": "string", "maxLength": 50 }, "vendor_ranges": {}, "operations": {}, "max_concurrency": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "reported_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "driver_version", "provider", "reported_at" ] }, "PaginatedTaskDispatchList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TaskDispatch" } } } }, "PatchedCollectorEnrollTokenRequest": { "type": "object", "properties": { "site": { "type": "integer" }, "max_uses": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "expires_at": { "type": "string", "format": "date-time" }, "approval_mode": { "$ref": "#/components/schemas/ApprovalModeEnum" } } }, "CollectorSessionStateEnum": { "enum": [ "active", "stale", "draining", "dead" ], "type": "string", "description": "* `active` - Active\n* `stale` - Stale\n* `draining` - Draining\n* `dead` - Dead" }, "Collector": { "type": "object", "properties": { "collector_id": { "type": "string", "maxLength": 64 }, "site": { "type": "integer" }, "site_name": { "type": "string", "readOnly": true }, "hostname": { "type": "string", "maxLength": 255 }, "os": { "type": "string", "maxLength": 50 }, "arch": { "type": "string", "maxLength": 20 }, "version": { "type": "string", "maxLength": 50 }, "target_version": { "type": "string", "maxLength": 50 }, "update_requested_at": { "type": "string", "format": "date-time", "nullable": true }, "site_update_policy": { "type": "string", "readOnly": true }, "latest_version": { "type": "string", "readOnly": true }, "update_available": { "type": "string", "readOnly": true }, "update_status": { "type": "string", "readOnly": true }, "fips_requested": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/CollectorStatusEnum" }, "cert_serial": { "type": "string", "maxLength": 100 }, "cert_fingerprint_sha256": { "type": "string", "maxLength": 64 }, "cert_not_after": { "type": "string", "format": "date-time", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "readOnly": true }, "last_claim_at": { "type": "string", "readOnly": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_reason": { "type": "string" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorSession" }, "readOnly": true }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorCapability" }, "readOnly": true }, "live_session_state": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "vault_mode": { "$ref": "#/components/schemas/VaultModeEnum" }, "vault_mount": { "type": "integer", "nullable": true }, "vault_mount_name": { "type": "string", "readOnly": true }, "external_vault": { "type": "string", "format": "uuid", "nullable": true }, "external_vault_name": { "type": "string", "readOnly": true }, "data_mask_enabled": { "type": "boolean" } }, "required": [ "capabilities", "collector_id", "created_at", "external_vault_name", "last_claim_at", "last_seen_at", "latest_version", "live_session_state", "sessions", "site", "site_name", "site_update_policy", "update_available", "update_status", "vault_mount_name" ] }, "PaginatedCollectorReleaseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorRelease" } } } }, "ApprovalModeEnum": { "enum": [ "auto", "manual" ], "type": "string", "description": "* `auto` - Auto-approve\n* `manual` - Manual approval" }, "PaginatedTenantRequestList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TenantRequest" } } } }, "CollectorEnrollToken": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "site": { "type": "integer" }, "site_name": { "type": "string", "readOnly": true }, "max_uses": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "uses": { "type": "integer", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time" }, "approval_mode": { "$ref": "#/components/schemas/ApprovalModeEnum" }, "revoked_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "expires_at", "id", "revoked_at", "site", "site_name", "uses" ] }, "VaultModeEnum": { "enum": [ "A", "B", "C" ], "type": "string", "description": "* `A` - Local Vault\n* `B` - Cloud-Relayed\n* `C` - External Secret Manager" }, "CollectorEnrollTokenRequest": { "type": "object", "properties": { "site": { "type": "integer" }, "max_uses": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "expires_at": { "type": "string", "format": "date-time" }, "approval_mode": { "$ref": "#/components/schemas/ApprovalModeEnum" } }, "required": [ "expires_at", "site" ] }, "TaskDispatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "workflow_run_id": { "type": "string", "format": "uuid", "nullable": true }, "step_id": { "type": "string", "format": "uuid", "nullable": true }, "idempotency_key": { "type": "string", "maxLength": 128 }, "provider": { "type": "string", "maxLength": 100 }, "operation": { "type": "string", "maxLength": 100 }, "op_class": { "$ref": "#/components/schemas/OpClassEnum" }, "target_ref": { "type": "string", "maxLength": 255 }, "device": { "type": "integer", "nullable": true }, "device_name": { "type": "string", "readOnly": true, "default": "" }, "site": { "type": "integer", "nullable": true }, "site_name": { "type": "string", "readOnly": true, "default": "" }, "collector": { "type": "string", "nullable": true }, "collector_id_display": { "type": "string", "readOnly": true, "default": "" }, "attempt": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "state": { "$ref": "#/components/schemas/TaskDispatchStateEnum" }, "not_before": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "leased_until": { "type": "string", "format": "date-time", "nullable": true }, "result": { "nullable": true }, "result_at": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string" }, "reconcile_attempts": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "change_ref": { "type": "string", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "collector_id_display", "created_at", "device_name", "expires_at", "id", "idempotency_key", "not_before", "op_class", "operation", "provider", "site_name", "target_ref" ] }, "PaginatedTenantList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } } } }, "CollectorSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "gateway_instance": { "type": "string", "maxLength": 100 }, "established_at": { "type": "string", "format": "date-time", "readOnly": true }, "last_heartbeat_at": { "type": "string", "format": "date-time", "readOnly": true }, "state": { "$ref": "#/components/schemas/CollectorSessionStateEnum" }, "hello": {}, "effective_limits": {}, "queue_depth": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648 }, "drain_requested": { "type": "boolean" }, "drain_reason": { "type": "string" } }, "required": [ "established_at", "id", "last_heartbeat_at" ] }, "PatchedCollectorReleaseRequest": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 50 }, "channel": { "$ref": "#/components/schemas/ChannelEnum" }, "is_latest": { "type": "boolean" }, "security": { "type": "boolean" }, "min_version": { "type": "string", "maxLength": 50 }, "notes": { "type": "string" }, "manifest_url": { "type": "string", "maxLength": 500 } } }, "PaginatedCollectorList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Collector" } } } }, "ChannelEnum": { "enum": [ "stable", "beta" ], "type": "string", "description": "* `stable` - Stable\n* `beta` - Beta" }, "CollectorReleaseRequest": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 50 }, "channel": { "$ref": "#/components/schemas/ChannelEnum" }, "is_latest": { "type": "boolean" }, "security": { "type": "boolean" }, "min_version": { "type": "string", "maxLength": 50 }, "notes": { "type": "string" }, "manifest_url": { "type": "string", "maxLength": 500 } }, "required": [ "version" ] }, "TenantStateEnum": { "enum": [ "provisioning", "active", "suspended", "expired", "purging", "deleted" ], "type": "string", "description": "* `provisioning` - Provisioning\n* `active` - Active\n* `suspended` - Suspended\n* `expired` - Expired\n* `purging` - Purging\n* `deleted` - Deleted" }, "OpClassEnum": { "enum": [ "read", "mutate_reconcilable", "mutate_terminal" ], "type": "string", "description": "* `read` - Read\n* `mutate_reconcilable` - Mutate (Reconcilable)\n* `mutate_terminal` - Mutate (Terminal)" }, "PaginatedEulaAcceptanceList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EulaAcceptance" } } } } } } }