nathan/vctp2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs
continuous-integration/drone/push Build is passing
Details

Browse Source
This commit is contained in:
Nathan Coad
2026-04-17 14:00:48 +10:00
parent ae3e2be89a
commit 7848557002
32 changed files with 1226 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/router/docs/docs.go
+287 -25
View File
@@ -41,9 +41,103 @@ const docTemplate = `{
}
}
},
"/api/auth/login": {
"post": {
"description": "Authenticates a username/password against LDAP and returns a signed access token.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Login",
"parameters": [
{
"description": "Login credentials",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.AuthLoginRequest"
}
}
],
"responses": {
"200": {
"description": "Login success",
"schema": {
"$ref": "#/definitions/models.AuthLoginResponse"
}
},
"400": {
"description": "Invalid request",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"401": {
"description": "Invalid credentials",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"500": {
"description": "Server error",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"503": {
"description": "Authentication disabled",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/auth/me": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Returns JWT claims for the currently authenticated bearer token.\nRequires Bearer authentication.",
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Who am I",
"responses": {
"200": {
"description": "Authenticated identity",
"schema": {
"$ref": "#/definitions/models.AuthMeResponse"
}
},
"401": {
"description": "Missing or invalid authentication context",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/cleanup/updates": {
"delete": {
"description": "Deprecated: Removes update records that are no longer associated with a VM.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes update records that are no longer associated with a VM.\nRequires Bearer authentication with the admin role.",
"produces": [
"text/plain"
],
@@ -106,7 +200,12 @@ const docTemplate = `{
},
"/api/diagnostics/daily-creation": {
"get": {
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.",
"security": [
{
"BearerAuth": []
}
],
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/json"
],
@@ -153,7 +252,12 @@ const docTemplate = `{
},
"/api/encrypt": {
"post": {
"description": "Encrypts a plaintext value and returns the ciphertext.",
"security": [
{
"BearerAuth": []
}
],
"description": "Encrypts a plaintext value and returns the ciphertext.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -202,7 +306,12 @@ const docTemplate = `{
},
"/api/event/vm/create": {
"post": {
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -249,7 +358,12 @@ const docTemplate = `{
},
"/api/event/vm/delete": {
"post": {
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -296,7 +410,12 @@ const docTemplate = `{
},
"/api/event/vm/modify": {
"post": {
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -343,7 +462,12 @@ const docTemplate = `{
},
"/api/event/vm/move": {
"post": {
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -390,7 +514,12 @@ const docTemplate = `{
},
"/api/import/vm": {
"post": {
"description": "Deprecated: Imports existing VM inventory data in bulk.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Imports existing VM inventory data in bulk.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -431,7 +560,12 @@ const docTemplate = `{
},
"/api/inventory/vm/delete": {
"delete": {
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -474,7 +608,12 @@ const docTemplate = `{
},
"/api/inventory/vm/update": {
"post": {
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -501,7 +640,12 @@ const docTemplate = `{
},
"/api/report/inventory": {
"get": {
"description": "Generates an inventory XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an inventory XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -527,7 +671,12 @@ const docTemplate = `{
},
"/api/report/snapshot": {
"get": {
"description": "Downloads a snapshot table as an XLSX file.",
"security": [
{
"BearerAuth": []
}
],
"description": "Downloads a snapshot table as an XLSX file.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -568,7 +717,12 @@ const docTemplate = `{
},
"/api/report/updates": {
"get": {
"description": "Generates an updates XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an updates XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -594,7 +748,12 @@ const docTemplate = `{
},
"/api/snapshots/aggregate": {
"post": {
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.",
"security": [
{
"BearerAuth": []
}
],
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -648,7 +807,12 @@ const docTemplate = `{
},
"/api/snapshots/hourly/force": {
"post": {
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.",
"security": [
{
"BearerAuth": []
}
],
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -692,7 +856,12 @@ const docTemplate = `{
},
"/api/snapshots/migrate": {
"post": {
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -718,7 +887,12 @@ const docTemplate = `{
},
"/api/snapshots/regenerate-hourly-reports": {
"post": {
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.",
"security": [
{
"BearerAuth": []
}
],
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -744,7 +918,12 @@ const docTemplate = `{
},
"/api/snapshots/repair": {
"post": {
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -764,7 +943,12 @@ const docTemplate = `{
},
"/api/snapshots/repair/all": {
"post": {
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -784,7 +968,12 @@ const docTemplate = `{
},
"/api/vcenters/cache/rebuild": {
"post": {
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -1120,6 +1309,72 @@ const docTemplate = `{
}
},
"definitions": {
"models.AuthLoginRequest": {
"type": "object",
"properties": {
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"models.AuthLoginResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"token_type": {
"type": "string"
}
}
},
"models.AuthMeResponse": {
"type": "object",
"properties": {
"audience": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"issued_at": {
"type": "integer"
},
"issuer": {
"type": "string"
},
"not_before": {
"type": "integer"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"subject": {
"type": "string"
},
"token_id": {
"type": "string"
}
}
},
"models.CloudEventReceived": {
"type": "object",
"properties": {
@@ -1613,17 +1868,24 @@ const docTemplate = `{
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "",
Version: "1.0",
Host: "",
BasePath: "",
Schemes: []string{},
Title: "",
Description: "",
BasePath: "/",
Schemes: []string{"http", "https"},
Title: "vCTP API",
Description: "vCTP API endpoints for inventory snapshots, reporting, and administration.",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
server/router/docs/swagger.json
+291 -21
View File
@@ -1,8 +1,16 @@
{
"schemes": [
"http",
"https"
],
"swagger": "2.0",
"info": {
"contact": {}
"description": "vCTP API endpoints for inventory snapshots, reporting, and administration.",
"title": "vCTP API",
"contact": {},
"version": "1.0"
},
"basePath": "/",
"paths": {
"/": {
"get": {
@@ -30,9 +38,103 @@
}
}
},
"/api/auth/login": {
"post": {
"description": "Authenticates a username/password against LDAP and returns a signed access token.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Login",
"parameters": [
{
"description": "Login credentials",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.AuthLoginRequest"
}
}
],
"responses": {
"200": {
"description": "Login success",
"schema": {
"$ref": "#/definitions/models.AuthLoginResponse"
}
},
"400": {
"description": "Invalid request",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"401": {
"description": "Invalid credentials",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"500": {
"description": "Server error",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"503": {
"description": "Authentication disabled",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/auth/me": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Returns JWT claims for the currently authenticated bearer token.\nRequires Bearer authentication.",
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Who am I",
"responses": {
"200": {
"description": "Authenticated identity",
"schema": {
"$ref": "#/definitions/models.AuthMeResponse"
}
},
"401": {
"description": "Missing or invalid authentication context",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/cleanup/updates": {
"delete": {
"description": "Deprecated: Removes update records that are no longer associated with a VM.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes update records that are no longer associated with a VM.\nRequires Bearer authentication with the admin role.",
"produces": [
"text/plain"
],
@@ -95,7 +197,12 @@
},
"/api/diagnostics/daily-creation": {
"get": {
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.",
"security": [
{
"BearerAuth": []
}
],
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/json"
],
@@ -142,7 +249,12 @@
},
"/api/encrypt": {
"post": {
"description": "Encrypts a plaintext value and returns the ciphertext.",
"security": [
{
"BearerAuth": []
}
],
"description": "Encrypts a plaintext value and returns the ciphertext.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -191,7 +303,12 @@
},
"/api/event/vm/create": {
"post": {
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -238,7 +355,12 @@
},
"/api/event/vm/delete": {
"post": {
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -285,7 +407,12 @@
},
"/api/event/vm/modify": {
"post": {
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -332,7 +459,12 @@
},
"/api/event/vm/move": {
"post": {
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -379,7 +511,12 @@
},
"/api/import/vm": {
"post": {
"description": "Deprecated: Imports existing VM inventory data in bulk.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Imports existing VM inventory data in bulk.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -420,7 +557,12 @@
},
"/api/inventory/vm/delete": {
"delete": {
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -463,7 +605,12 @@
},
"/api/inventory/vm/update": {
"post": {
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -490,7 +637,12 @@
},
"/api/report/inventory": {
"get": {
"description": "Generates an inventory XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an inventory XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -516,7 +668,12 @@
},
"/api/report/snapshot": {
"get": {
"description": "Downloads a snapshot table as an XLSX file.",
"security": [
{
"BearerAuth": []
}
],
"description": "Downloads a snapshot table as an XLSX file.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -557,7 +714,12 @@
},
"/api/report/updates": {
"get": {
"description": "Generates an updates XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an updates XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -583,7 +745,12 @@
},
"/api/snapshots/aggregate": {
"post": {
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.",
"security": [
{
"BearerAuth": []
}
],
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -637,7 +804,12 @@
},
"/api/snapshots/hourly/force": {
"post": {
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.",
"security": [
{
"BearerAuth": []
}
],
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -681,7 +853,12 @@
},
"/api/snapshots/migrate": {
"post": {
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -707,7 +884,12 @@
},
"/api/snapshots/regenerate-hourly-reports": {
"post": {
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.",
"security": [
{
"BearerAuth": []
}
],
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -733,7 +915,12 @@
},
"/api/snapshots/repair": {
"post": {
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -753,7 +940,12 @@
},
"/api/snapshots/repair/all": {
"post": {
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -773,7 +965,12 @@
},
"/api/vcenters/cache/rebuild": {
"post": {
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -1109,6 +1306,72 @@
}
},
"definitions": {
"models.AuthLoginRequest": {
"type": "object",
"properties": {
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"models.AuthLoginResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"token_type": {
"type": "string"
}
}
},
"models.AuthMeResponse": {
"type": "object",
"properties": {
"audience": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"issued_at": {
"type": "integer"
},
"issuer": {
"type": "string"
},
"not_before": {
"type": "integer"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"subject": {
"type": "string"
},
"token_id": {
"type": "string"
}
}
},
"models.CloudEventReceived": {
"type": "object",
"properties": {
@@ -1602,5 +1865,12 @@
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}
server/router/docs/swagger.yaml
+215 -35
View File
@@ -1,4 +1,48 @@
basePath: /
definitions:
models.AuthLoginRequest:
properties:
password:
type: string
username:
type: string
type: object
models.AuthLoginResponse:
properties:
access_token:
type: string
expires_at:
type: integer
token_type:
type: string
type: object
models.AuthMeResponse:
properties:
audience:
type: string
expires_at:
type: integer
groups:
items:
type: string
type: array
issued_at:
type: integer
issuer:
type: string
not_before:
type: integer
roles:
items:
type: string
type: array
status:
type: string
subject:
type: string
token_id:
type: string
type: object
models.CloudEventReceived:
properties:
cloudEvent:
@@ -320,6 +364,9 @@ definitions:
type: object
info:
contact: {}
description: vCTP API endpoints for inventory snapshots, reporting, and administration.
title: vCTP API
version: "1.0"
paths:
/:
get:
@@ -338,11 +385,72 @@ paths:
summary: Home page
tags:
- ui
/api/auth/login:
post:
consumes:
- application/json
description: Authenticates a username/password against LDAP and returns a signed
access token.
parameters:
- description: Login credentials
in: body
name: payload
required: true
schema:
$ref: '#/definitions/models.AuthLoginRequest'
produces:
- application/json
responses:
"200":
description: Login success
schema:
$ref: '#/definitions/models.AuthLoginResponse'
"400":
description: Invalid request
schema:
$ref: '#/definitions/models.ErrorResponse'
"401":
description: Invalid credentials
schema:
$ref: '#/definitions/models.ErrorResponse'
"500":
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
"503":
description: Authentication disabled
schema:
$ref: '#/definitions/models.ErrorResponse'
summary: Login
tags:
- auth
/api/auth/me:
get:
description: |-
Returns JWT claims for the currently authenticated bearer token.
Requires Bearer authentication.
produces:
- application/json
responses:
"200":
description: Authenticated identity
schema:
$ref: '#/definitions/models.AuthMeResponse'
"401":
description: Missing or invalid authentication context
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Who am I
tags:
- auth
/api/cleanup/updates:
delete:
deprecated: true
description: 'Deprecated: Removes update records that are no longer associated
with a VM.'
description: |-
Deprecated: Removes update records that are no longer associated with a VM.
Requires Bearer authentication with the admin role.
produces:
- text/plain
responses:
@@ -354,6 +462,8 @@ paths:
description: Server error
schema:
type: string
security:
- BearerAuth: []
summary: Cleanup updates (deprecated)
tags:
- maintenance
@@ -384,8 +494,9 @@ paths:
- maintenance
/api/diagnostics/daily-creation:
get:
description: Returns counts of daily summary rows missing CreationTime and sample
rows for the given date.
description: |-
Returns counts of daily summary rows missing CreationTime and sample rows for the given date.
Requires Bearer authentication with the viewer role (admin also allowed).
parameters:
- description: Daily date (YYYY-MM-DD)
in: query
@@ -411,6 +522,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Daily summary CreationTime diagnostics
tags:
- diagnostics
@@ -418,7 +531,9 @@ paths:
post:
consumes:
- application/json
description: Encrypts a plaintext value and returns the ciphertext.
description: |-
Encrypts a plaintext value and returns the ciphertext.
Requires Bearer authentication with the admin role.
parameters:
- description: Plaintext payload
in: body
@@ -443,6 +558,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Encrypt data
tags:
- crypto
@@ -451,8 +568,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM create CloudEvent and stores the event
data.'
description: |-
Deprecated: Parses a VM create CloudEvent and stores the event data.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -475,6 +593,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM create event (deprecated)
tags:
- events
@@ -483,8 +603,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM delete CloudEvent and marks the VM as
deleted in inventory.'
description: |-
Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -507,6 +628,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM delete event (deprecated)
tags:
- events
@@ -515,8 +638,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM modify CloudEvent and creates an update
record when relevant changes are detected.'
description: |-
Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -539,6 +663,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM modify event (deprecated)
tags:
- events
@@ -547,8 +673,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM move CloudEvent and creates an update
record.'
description: |-
Deprecated: Parses a VM move CloudEvent and creates an update record.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -571,6 +698,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM move event (deprecated)
tags:
- events
@@ -579,7 +708,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Imports existing VM inventory data in bulk.'
description: |-
Deprecated: Imports existing VM inventory data in bulk.
Requires Bearer authentication with the admin role.
parameters:
- description: Bulk import payload
in: body
@@ -598,14 +729,17 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Import VMs (deprecated)
tags:
- inventory
/api/inventory/vm/delete:
delete:
deprecated: true
description: 'Deprecated: Removes a VM inventory entry by VM ID and datacenter
name.'
description: |-
Deprecated: Removes a VM inventory entry by VM ID and datacenter name.
Requires Bearer authentication with the admin role.
parameters:
- description: VM ID
in: query
@@ -628,14 +762,17 @@ paths:
description: Invalid request
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Cleanup VM inventory entry (deprecated)
tags:
- inventory
/api/inventory/vm/update:
post:
deprecated: true
description: 'Deprecated: Queries vCenter and updates inventory records with
missing details.'
description: |-
Deprecated: Queries vCenter and updates inventory records with missing details.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -647,12 +784,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Refresh VM details (deprecated)
tags:
- inventory
/api/report/inventory:
get:
description: Generates an inventory XLSX report and returns it as a file download.
description: |-
Generates an inventory XLSX report and returns it as a file download.
Requires Bearer authentication with the viewer role (admin also allowed).
produces:
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
responses:
@@ -664,12 +805,16 @@ paths:
description: Report generation failed
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download inventory report
tags:
- reports
/api/report/snapshot:
get:
description: Downloads a snapshot table as an XLSX file.
description: |-
Downloads a snapshot table as an XLSX file.
Requires Bearer authentication with the viewer role (admin also allowed).
parameters:
- description: Snapshot table name
in: query
@@ -691,12 +836,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download snapshot report
tags:
- snapshots
/api/report/updates:
get:
description: Generates an updates XLSX report and returns it as a file download.
description: |-
Generates an updates XLSX report and returns it as a file download.
Requires Bearer authentication with the viewer role (admin also allowed).
produces:
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
responses:
@@ -708,13 +857,16 @@ paths:
description: Report generation failed
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download updates report
tags:
- reports
/api/snapshots/aggregate:
post:
description: Forces regeneration of a daily or monthly summary table for a specified
date or month.
description: |-
Forces regeneration of a daily or monthly summary table for a specified date or month.
Requires Bearer authentication with the admin role.
parameters:
- description: 'Aggregation type: daily or monthly'
in: query
@@ -745,6 +897,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Force snapshot aggregation
tags:
- snapshots
@@ -752,8 +906,9 @@ paths:
post:
consumes:
- application/json
description: Manually trigger an hourly snapshot for all configured vCenters.
Requires confirmation text to avoid accidental execution.
description: |-
Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.
Requires Bearer authentication with the admin role.
parameters:
- description: Confirmation text; must be 'FORCE'
in: query
@@ -775,13 +930,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Trigger hourly snapshot (manual)
tags:
- snapshots
/api/snapshots/migrate:
post:
description: Rebuilds the snapshot registry from existing tables and renames
hourly tables to epoch-based names.
description: |-
Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -793,13 +951,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.SnapshotMigrationResponse'
security:
- BearerAuth: []
summary: Migrate snapshot registry
tags:
- snapshots
/api/snapshots/regenerate-hourly-reports:
post:
description: Regenerates XLSX reports for hourly snapshots when the report files
are missing or empty.
description: |-
Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -811,13 +972,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Regenerate hourly snapshot reports
tags:
- snapshots
/api/snapshots/repair:
post:
description: Backfills SnapshotTime and lifecycle info for existing daily summary
tables and reruns monthly lifecycle refinement using hourly data.
description: |-
Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -825,13 +989,16 @@ paths:
description: OK
schema:
$ref: '#/definitions/models.SnapshotRepairResponse'
security:
- BearerAuth: []
summary: Repair daily summaries
tags:
- snapshots
/api/snapshots/repair/all:
post:
description: Rebuilds snapshot registry, backfills per-vCenter totals, repairs
daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
description: |-
Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -839,13 +1006,16 @@ paths:
description: OK
schema:
$ref: '#/definitions/models.SnapshotRepairSuiteResponse'
security:
- BearerAuth: []
summary: Run full snapshot repair suite
tags:
- snapshots
/api/vcenters/cache/rebuild:
post:
description: Rebuilds cached folder/resource-pool/host(cluster+datacenter) references
from vCenter and rewrites the database cache tables.
description: |-
Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.
Requires Bearer authentication with the admin role.
parameters:
- description: Optional single vCenter URL to rebuild; defaults to all configured
vCenters
@@ -871,6 +1041,8 @@ paths:
description: All rebuild attempts failed
schema:
$ref: '#/definitions/models.VcenterCacheRebuildResponse'
security:
- BearerAuth: []
summary: Rebuild vCenter object cache
tags:
- vcenters
@@ -1069,4 +1241,12 @@ paths:
summary: Trace VM history
tags:
- vm
schemes:
- http
- https
securityDefinitions:
BearerAuth:
in: header
name: Authorization
type: apiKey
swagger: "2.0"