{ "swagger": "2.0", "info": { "contact": {} }, "paths": { "/agent/git-token": { "get": { "security": [ { "AgentAuth": [] } ], "description": "Returns a GitHub installation token for repository access. Rate limited.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Agent" ], "summary": "Request Git token", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.AgentGitTokenResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "501": { "description": "Not Implemented", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } } } } }, "/agent/server-info": { "get": { "security": [ { "AgentAuth": [] } ], "description": "Returns repository configuration for a server. Authenticated via agent token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Agent" ], "summary": "Get server info (Agent Token)", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.ServerInfoResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } } } } }, "/agent/status": { "post": { "security": [ { "AgentAuth": [] } ], "description": "Receives status updates from agents including drift detection and errors. Authenticated via agent token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Agent" ], "summary": "Update agent status (Agent Token)", "parameters": [ { "description": "Status update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.AgentStatusPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } } } } }, "/auth/login": { "post": { "description": "Authenticate with username and password to receive a JWT token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Auth" ], "summary": "User login", "parameters": [ { "description": "Login credentials", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.LoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.LoginResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/auth/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get the authenticated user's information.", "produces": [ "application/json" ], "tags": [ "Auth" ], "summary": "Get current user", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.UserSummary" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/bootstrap/admin": { "post": { "description": "Create the first admin user using the bootstrap secret. Only available when bootstrap is enabled.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Auth" ], "summary": "Create bootstrap admin", "parameters": [ { "description": "Bootstrap credentials", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.BootstrapAdminRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/pkg_server.BootstrapAdminResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/bootstrap/status": { "get": { "description": "Check if bootstrap mode is enabled and get the secret file path.", "produces": [ "application/json" ], "tags": [ "Auth" ], "summary": "Get bootstrap status", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/environments/health": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns health status for all environments including webhook status and git token rate limits", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Environments" ], "summary": "Get environment health", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/environments/{environmentID}/test-webhook": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends a test notification to the environment's configured webhook URL", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Webhooks" ], "summary": "Test webhook", "parameters": [ { "type": "integer", "description": "Environment ID", "name": "environmentID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/healthz": { "get": { "description": "Kubernetes-style liveness check. Returns healthy if service is running and database is reachable.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Liveness probe", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.HealthCheckResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/pkg_server.HealthCheckResponse" } } } } }, "/metrics/connectivity": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get agent online/offline status for all servers.", "produces": [ "application/json" ], "tags": [ "Metrics" ], "summary": "Get agent connectivity", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.AgentConnectivityResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/metrics/drift": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get drift event metrics over time.", "produces": [ "application/json" ], "tags": [ "Metrics" ], "summary": "Get drift metrics", "parameters": [ { "type": "integer", "default": 7, "description": "Number of days", "name": "days", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.DriftMetricsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/metrics/reconciliation": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get reconciliation success/failure metrics over time.", "produces": [ "application/json" ], "tags": [ "Metrics" ], "summary": "Get reconciliation metrics", "parameters": [ { "type": "integer", "default": 7, "description": "Number of days", "name": "days", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.ReconciliationMetricsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/readyz": { "get": { "description": "Kubernetes-style readiness check. Returns healthy if service is ready to accept traffic.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Readiness probe", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.HealthCheckResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/pkg_server.HealthCheckResponse" } } } } }, "/servers": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves a paginated list of servers with their latest status", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "List all servers", "parameters": [ { "type": "integer", "default": 100, "description": "Maximum number of servers to return (1-500)", "name": "limit", "in": "query" }, { "type": "integer", "default": 0, "description": "Number of servers to skip", "name": "offset", "in": "query" }, { "type": "string", "description": "Sort field (name, created_at, status)", "name": "sort", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.ServerWithStatus" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new server with an initial agent token for deployment", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Create a new server", "parameters": [ { "description": "Server creation request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.CreateServerRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/pkg_server.CreateServerResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves detailed information about a specific server including its latest status", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Get server details", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.ServerWithStatus" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates a server's configuration (name only, git config inherited from environment)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Update server", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "description": "Server update request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.UpdateServerRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.Server" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-deletes a server and deactivates all its agent tokens", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Delete server", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/auto-reconcile": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Toggles the auto-reconciliation setting for a server", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Toggle auto-reconcile", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/drift": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves detailed drift information for a server including packages, services, and files", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Get server drift details", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.DriftDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/info": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns repository configuration for a server. Used by agents for initial setup.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Agent" ], "summary": "Get server info (JWT)", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.ServerInfoResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } } } } }, "/servers/{serverID}/install-instructions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns installation instructions for deploying the agent on a server", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Get install instructions", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/install-script": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Generates a bash script for installing the agent on a server", "produces": [ "text/x-shellscript" ], "tags": [ "Servers" ], "summary": "Get install script", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "type": "string", "description": "Agent token", "name": "token", "in": "query", "required": true }, { "type": "string", "default": "latest", "description": "Agent version", "name": "version", "in": "query" }, { "type": "string", "description": "CA certificate for TLS verification", "name": "ca_cert", "in": "query" } ], "responses": { "200": { "description": "Bash install script", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/status": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Receives status updates from agents including drift detection and errors", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Agent" ], "summary": "Update agent status (JWT)", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "description": "Status update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.AgentStatusPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Error" } } } } }, "/servers/{serverID}/status-history": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves paginated history of agent status updates for a server", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Servers" ], "summary": "Get server status history", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "type": "integer", "default": 20, "description": "Number of entries per page (1-100)", "name": "limit", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/tokens": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves all active agent tokens for a server", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Tokens" ], "summary": "List server tokens", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.AgentToken" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new agent token for a server. The token is only returned once.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Tokens" ], "summary": "Create server token", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "description": "Token creation request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.CreateServerTokenRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/pkg_server.CreateServerTokenResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/servers/{serverID}/tokens/{tokenID}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deactivates an agent token, preventing further authentication", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Tokens" ], "summary": "Deactivate token", "parameters": [ { "type": "string", "description": "Server ID", "name": "serverID", "in": "path", "required": true }, { "type": "integer", "description": "Token ID", "name": "tokenID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/tokens/expiring": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns tokens that will expire within the specified number of days", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Tokens" ], "summary": "Get expiring tokens", "parameters": [ { "type": "integer", "default": 7, "description": "Days until expiration (1-365)", "name": "days", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/users": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all users. Admin only.", "produces": [ "application/json" ], "tags": [ "Users" ], "summary": "List users", "parameters": [ { "type": "integer", "default": 100, "description": "Limit", "name": "limit", "in": "query" }, { "type": "integer", "default": 0, "description": "Offset", "name": "offset", "in": "query" }, { "type": "string", "description": "Filter by role", "name": "role", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.ListUsersResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new user. Admin only.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Users" ], "summary": "Create user", "parameters": [ { "description": "User details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.CreateUserRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/pkg_server.CreateUserResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/users/{userID}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a user. Admin only. Requires username confirmation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Users" ], "summary": "Delete user", "parameters": [ { "type": "integer", "description": "User ID", "name": "userID", "in": "path", "required": true }, { "description": "Confirmation", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/pkg_server.DeleteUserRequest" } } ], "responses": { "204": { "description": "User deleted" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } }, "/validate-config": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Validates a config.yaml file for syntax errors and invalid values", "consumes": [ "text/yaml" ], "produces": [ "application/json" ], "tags": [ "Config" ], "summary": "Validate config", "parameters": [ { "description": "YAML configuration file content", "name": "config", "in": "body", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/pkg_server.ValidateConfigResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/pkg_server.ValidateConfigResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } }, "405": { "description": "Method Not Allowed", "schema": { "$ref": "#/definitions/pkg_server.ErrorResponse" } } } } } }, "definitions": { "github_com_pullbase_pullbase_server_pkg_apierrors.Error": { "type": "object", "properties": { "err": { "description": "Underlying error, if any" }, "kind": { "description": "The category of error", "allOf": [ { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_apierrors.Kind" } ] }, "message": { "description": "Human-readable error message", "type": "string" }, "op": { "description": "Operation that failed (e.g., \"GetServer\", \"CreateUser\")", "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_apierrors.Kind": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "x-enum-varnames": [ "KindUnknown", "KindNotFound", "KindUnauthorized", "KindForbidden", "KindValidation", "KindConflict", "KindInternal", "KindBadRequest", "KindTooManyRequests", "KindNotImplemented" ] }, "github_com_pullbase_pullbase_server_pkg_configvalidate.ValidationError": { "type": "object", "properties": { "column": { "type": "integer" }, "field": { "type": "string" }, "line": { "type": "integer" }, "message": { "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_models.AgentToken": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by_user_id": { "type": "integer" }, "description": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "last_used_at": { "type": "string" }, "server_id": { "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_models.DriftDetails": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.DriftItem" } }, "packages": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.DriftItem" } }, "services": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.DriftItem" } }, "summary": { "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_models.DriftItem": { "type": "object", "properties": { "actual": { "type": "string" }, "expected": { "type": "string" }, "message": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_models.GitProvider": { "type": "string", "enum": [ "github" ], "x-enum-varnames": [ "ProviderGitHub" ] }, "github_com_pullbase_pullbase_server_pkg_models.Server": { "type": "object", "properties": { "auto_reconcile": { "type": "boolean" }, "created_at": { "type": "string" }, "environment_id": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "target_commit_hash": { "type": "string" }, "updated_at": { "type": "string" } } }, "github_com_pullbase_pullbase_server_pkg_models.ServerWithStatus": { "type": "object", "properties": { "auto_reconcile": { "type": "boolean" }, "created_at": { "type": "string" }, "environment_id": { "type": "integer" }, "environment_name": { "type": "string" }, "id": { "type": "string" }, "last_agent_version": { "type": "string" }, "last_commit_hash": { "type": "string" }, "last_error_message": { "type": "string" }, "last_is_drifted": { "type": "boolean" }, "last_status": { "type": "string" }, "last_timestamp": { "type": "string" }, "name": { "type": "string" }, "target_commit_hash": { "type": "string" }, "updated_at": { "type": "string" } } }, "pkg_server.AgentConnectivityEntry": { "type": "object", "properties": { "is_online": { "type": "boolean" }, "last_seen": { "type": "string" }, "server_id": { "type": "string" }, "server_name": { "type": "string" }, "status": { "type": "string" } } }, "pkg_server.AgentConnectivityResponse": { "type": "object", "properties": { "agent_statuses": { "type": "array", "items": { "$ref": "#/definitions/pkg_server.AgentConnectivityEntry" } }, "offline_agents": { "type": "integer" }, "online_agents": { "type": "integer" }, "stale_threshold": { "type": "string" }, "total_agents": { "type": "integer" } } }, "pkg_server.AgentGitTokenResponse": { "type": "object", "properties": { "app_slug": { "type": "string" }, "authentication": { "type": "string" }, "expires_at": { "type": "string" }, "installation_id": { "type": "integer" }, "provider": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.GitProvider" }, "repo_url": { "type": "string" }, "repository_id": { "type": "integer" }, "token": { "type": "string" } } }, "pkg_server.AgentStatusPayload": { "type": "object", "properties": { "agent_version": { "type": "string" }, "commit_hash": { "type": "string" }, "drift_details": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.DriftDetails" }, "error_message": { "type": "string" }, "is_drifted": { "type": "boolean" }, "status": { "type": "string" } } }, "pkg_server.BootstrapAdminRequest": { "type": "object", "properties": { "bootstrap_secret": { "type": "string" }, "password": { "type": "string" }, "username": { "type": "string" } } }, "pkg_server.BootstrapAdminResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "user": { "$ref": "#/definitions/pkg_server.UserSummary" } } }, "pkg_server.CheckResult": { "type": "object", "properties": { "error": { "type": "string" }, "latency_ms": { "type": "integer" }, "status": { "$ref": "#/definitions/pkg_server.HealthStatus" }, "version": { "type": "integer" } } }, "pkg_server.CreateServerRequest": { "type": "object", "properties": { "environment_id": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "pkg_server.CreateServerResponse": { "type": "object", "properties": { "agent_token": { "type": "string" }, "auto_reconcile": { "type": "boolean" }, "created_at": { "type": "string" }, "environment_id": { "type": "integer" }, "id": { "type": "string" }, "installation_info": { "type": "object", "properties": { "example_cmd": { "type": "string" }, "instructions": { "type": "string" } } }, "name": { "type": "string" }, "target_commit_hash": { "type": "string" }, "updated_at": { "type": "string" } } }, "pkg_server.CreateServerTokenRequest": { "type": "object", "properties": { "description": { "type": "string" }, "expires_in": { "description": "Optional expiration in days", "type": "integer" } } }, "pkg_server.CreateServerTokenResponse": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by_user_id": { "type": "integer" }, "description": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "integer" }, "installation_info": { "type": "object", "properties": { "example_cmd": { "type": "string" }, "instructions": { "type": "string" } } }, "is_active": { "type": "boolean" }, "last_used_at": { "type": "string" }, "server_id": { "type": "string" }, "token": { "description": "The actual token (only returned once)", "type": "string" } } }, "pkg_server.CreateUserRequest": { "type": "object", "properties": { "password": { "type": "string" }, "role": { "type": "string" }, "username": { "type": "string" } } }, "pkg_server.CreateUserResponse": { "type": "object", "properties": { "user": { "$ref": "#/definitions/pkg_server.UserSummary" } } }, "pkg_server.DeleteUserRequest": { "type": "object", "properties": { "confirm_username": { "type": "string" } } }, "pkg_server.DriftDetailsResponse": { "type": "object", "properties": { "commit_hash": { "type": "string" }, "detected_at": { "type": "string" }, "drift_details": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_models.DriftDetails" }, "is_drifted": { "type": "boolean" }, "server_id": { "type": "string" }, "server_name": { "type": "string" } } }, "pkg_server.DriftMetricsResponse": { "type": "object", "properties": { "period": { "type": "string" }, "time_series": { "type": "array", "items": { "$ref": "#/definitions/pkg_server.TimeSeriesPoint" } }, "total_events": { "type": "integer" } } }, "pkg_server.ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" } } }, "pkg_server.HealthCheckResponse": { "type": "object", "properties": { "checks": { "type": "object", "additionalProperties": { "$ref": "#/definitions/pkg_server.CheckResult" } }, "service": { "type": "string" }, "status": { "$ref": "#/definitions/pkg_server.HealthStatus" } } }, "pkg_server.HealthStatus": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy", "unknown" ], "x-enum-varnames": [ "HealthStatusHealthy", "HealthStatusDegraded", "HealthStatusUnhealthy", "HealthStatusUnknown" ] }, "pkg_server.ListUsersResponse": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "role": { "type": "string" }, "total": { "type": "integer" }, "users": { "type": "array", "items": { "$ref": "#/definitions/pkg_server.UserSummary" } } } }, "pkg_server.LoginRequest": { "type": "object", "properties": { "environment_id": { "type": "integer" }, "password": { "type": "string" }, "server_id": { "description": "For backward compatibility", "type": "string" }, "username": { "type": "string" } } }, "pkg_server.LoginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "user": { "$ref": "#/definitions/pkg_server.UserSummary" } } }, "pkg_server.ReconciliationMetricsResponse": { "type": "object", "properties": { "period": { "type": "string" }, "success_rate": { "type": "number" }, "time_series": { "type": "array", "items": { "$ref": "#/definitions/pkg_server.TimeSeriesPoint" } }, "total_applied": { "type": "integer" }, "total_failed": { "type": "integer" } } }, "pkg_server.ServerInfoResponse": { "type": "object", "properties": { "auto_reconcile": { "type": "boolean" }, "branch": { "type": "string" }, "deploy_path": { "type": "string" }, "repo_url": { "type": "string" }, "target_commit_hash": { "type": "string" } } }, "pkg_server.TimeSeriesPoint": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "integer" } } }, "pkg_server.UpdateServerRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "pkg_server.UserSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "role": { "type": "string" }, "username": { "type": "string" } } }, "pkg_server.ValidateConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/github_com_pullbase_pullbase_server_pkg_configvalidate.ValidationError" } }, "valid": { "type": "boolean" } } } } }