P Planekeeper Internal Docs
Internal documentation — not for external distribution.

API Endpoints

API Architecture

The API is split into three separate specifications:

APIBase PathPurpose
Client/api/v1/clientOrganization-scoped operations (jobs, rules, alerts)
Agent/api/v1/agentRemote agent operations (heartbeat, tasks)
Internal/api/v1/internalAdmin operations (metrics, settings)

Swagger UI:

  • Client API: /api/v1/swagger
  • Internal API: /api/v1/internal/swagger

System Endpoints

MethodPathDescription
GET/healthHealth check (no auth)

Agent Endpoints (Agent API)

MethodPathDescription
POST/heartbeat/{AgentUUID}Agent registration
POST/tasks/{AgentUUID}/pollPoll for next task
POST/tasks/{AgentUUID}/completeSubmit task results
POST/tasks/{AgentUUID}/log-failureLog submission failure

Agent Submission Logs

MethodPathAPIDescription
GET/agents/{agent_uuid}/submission-logsClient, InternalList submission logs for debugging

Gather Job Endpoints

MethodPathDescription
GET/gather-jobsList gather jobs
POST/gather-jobsCreate gather job
GET/gather-jobs/{id}Get gather job
PUT/gather-jobs/{id}Update gather job
POST/gather-jobs/{id}/runTrigger immediate run
POST/gather-jobs/{id}/clear-releasesDelete all releases for a job
GET/gather-jobs/summaryAggregate gather job counts by status (supports scope query param)

Scrape Job Endpoints

MethodPathDescription
GET/scrape-jobsList scrape jobs
POST/scrape-jobsCreate scrape job
GET/scrape-jobs/{id}Get scrape job
PUT/scrape-jobs/{id}Update scrape job
POST/scrape-jobs/{id}/runTrigger immediate run
POST/scrape-jobs/{id}/set-versionSet version for manual scrape job
GET/scrape-jobs/{id}/versionsGet version history
GET/scrape-jobs/summaryAggregate scrape job counts (total, scheduled, with versions; supports scope query param)

Helm Sync Job Endpoints

Helm sync jobs auto-discover charts in a Helm repository and create child gather jobs.

MethodPathAPIDescription
GET/helm-sync-jobsClient, InternalList helm sync jobs
POST/helm-sync-jobsClient, InternalCreate helm sync job
GET/helm-sync-jobs/{id}Client, InternalGet helm sync job details
PUT/helm-sync-jobs/{id}Client, InternalUpdate helm sync job
DELETE/helm-sync-jobs/{id}Client, InternalDelete helm sync job
POST/helm-sync-jobs/{id}/runClient, InternalTrigger helm sync immediately
GET/helm-sync-jobs/{id}/chartsClient, InternalList child gather jobs

Rules & Alerts

MethodPathDescription
GET/rulesList monitoring rules
POST/rulesCreate rule
GET/rules/{id}Get rule
PUT/rules/{id}Update rule
DELETE/rules/{id}Delete rule
POST/rules/{id}/toggleToggle active state
POST/rules/evaluateTrigger evaluation
GET/alert-configsList alert configs
POST/alert-configsCreate alert config
GET/alertsList alerts
GET/alerts/summaryAlert counts
GET/alerts/resolvedList resolved (historical) alerts
GET/alerts/{id}Get alert details
POST/alerts/{id}/acknowledgeAcknowledge alert
POST/alerts/{id}/unacknowledgeRemove acknowledgment
POST/alerts/{id}/resolveManually resolve alert
POST/alerts/acknowledgeBulk acknowledge
GET/alerts/{id}/deliveriesGet alert delivery history
GET/alerts/{id}/actionsGet audit trail of alert state changes

Notification Channels

MethodPathDescription
GET/notification-channelsList notification channels
POST/notification-channelsCreate notification channel
POST/notification-channels/validateValidate webhook config without creating
GET/notification-channels/{id}Get notification channel
PUT/notification-channels/{id}Update notification channel
DELETE/notification-channels/{id}Delete notification channel
POST/notification-channels/{id}/testTest channel connectivity
POST/notification-channels/{id}/toggleToggle channel active state
GET/notification-channels/{id}/statsGet channel health statistics

Notification Rules

MethodPathDescription
GET/notification-rulesList notification rules
POST/notification-rulesCreate notification rule
GET/notification-rules/{id}Get notification rule
PUT/notification-rules/{id}Update notification rule
DELETE/notification-rules/{id}Delete notification rule
POST/notification-rules/{id}/toggleToggle rule active state
GET/notification-rules/{id}/statsGet rule match statistics
POST/notification-rules/{id}/simulateSimulate rule matching

Notification Templates

Templates control the payload format for webhook deliveries. Templates are resolved in priority order: Channel > Organization > Global defaults.

MethodPathDescription
GET/notification-templatesList effective templates
PUT/notification-templates/{category}Set org template override
DELETE/notification-templates/{category}Remove org template override
POST/notification-templates/previewPreview template rendering

Notification Deliveries

MethodPathDescription
GET/notification-deliveriesList deliveries (filterable)
GET/notification-deliveries/deadList dead letters
POST/notification-deliveries/{id}/retryRetry dead letter

Notification Settings

MethodPathDescription
GET/notification-settingsGet org notification settings
PUT/notification-settingsUpdate org notification settings

Webhook Acknowledgment

External callback endpoints for alert acknowledgment (token-based, no API key required):

MethodPathDescription
GET/webhooks/acknowledge/{token}Acknowledge alert via browser (conditional auth based on channel config)
POST/webhooks/acknowledge/{token}Acknowledge alert via callback

Webhook Config Fields

Stored in config JSONB column:

FieldTypeRequiredDescription
urlstringYesWebhook endpoint URL
methodstringNoHTTP method (default: POST)
headersobjectNoCustom headers to include
timeout_secondsintNoRequest timeout (default: 30)
secretstringNoHMAC signing secret
event_templatesobjectNoEvent-specific body templates

Event-Specific Templates

{
  "url": "https://discord.com/api/webhooks/...",
  "event_templates": {
    "new_alert": "{\"content\": \"**{{.Alert.Severity | upper}}**: {{.Alert.ConfigName}}\"}",
    "acknowledged": "{\"content\": \"Acknowledged: {{.Alert.ConfigName}} by {{.AcknowledgedBy}}\"}",
    "resolved": "{\"content\": \"Resolved: {{.Alert.ConfigName}}\"}"
  }
}

Template Categories:

  • new_alert: For alert.created, alert.escalated events (includes {{.AcknowledgeURL}})
  • acknowledged: For alert.acknowledged, alert.unacknowledged events (includes {{.IsAcknowledged}}, {{.AcknowledgedBy}}, {{.AcknowledgedAt}})
  • resolved: For alert.resolved events (includes {{.ResolvedAt}})

API Keys Management

MethodPathDescription
GET/api-keysList API keys for organization
POST/api-keysCreate new API key (requires JWT auth)
GET/api-keys/{id}Get API key details (no secret returned)
PUT/api-keys/{id}Update API key name/description
POST/api-keys/{id}/toggleToggle API key active state
POST/api-keys/{id}/deactivatePermanently deactivate API key

User Feedback

MethodPathAPIDescription
POST/feedbackClientSubmit user feedback
GET/feedbackInternalList all feedback (admin)

Releases & Versions

MethodPathDescription
GET/releasesList upstream releases (includes metadata object; supports scope query param)
GET/releases/{id}Get release by ID (includes metadata object)
GET/releases/summaryAggregate release statistics (supports scope query param)
GET/versionsList version snapshots

Settings

MethodPathDescription
GET/settingsList settings
PUT/settings/{key}Update setting
GET/settings/effectiveEffective settings (global + org overrides)
GET/settings/org-overridesOrganization-specific overrides
PUT/settings/org-overrides/{key}Create/update org override
DELETE/settings/org-overrides/{key}Remove org override

UI selection helper endpoints that return simplified lists:

MethodPathDescription
GET/dropdowns/scrape-jobsScrape jobs for dropdown
GET/dropdowns/gather-jobsGather jobs for dropdown
GET/dropdowns/gather-jobs/globalGlobal gather jobs for dropdown
GET/dropdowns/rulesRules for dropdown
GET/dropdowns/notification-channelsChannels for dropdown

Permissions & Roles

MethodPathDescription
GET/permissions/meGet current user’s effective permissions (self, no permission check)
GET/permissions/matrixGet all resources and actions for role editing UI (no permission check)
GET/rolesList available roles (system + org custom)
POST/rolesCreate custom role with IAM-style policy document (accepts both policy_document and legacy permissions format)
GET/roles/{id}Get role details with policy document and legacy permissions
PUT/roles/{id}Update custom role (accepts both policy_document and legacy permissions format)
DELETE/roles/{id}Delete custom role
GET/members/{id}/rolesGet member’s assigned roles
PUT/members/{id}/rolesSet member’s role assignments

Validation

MethodPathDescription
POST/validate/regexValidate regex pattern

Internal API Endpoints

MethodPathDescription
GET/metricsSystem-wide metrics
GET/pending-contributionsList pending contribution suggestions
GET/pending-contributions/countCount pending contributions (for badge)
POST/pending-contributions/gather/{id}/approveApprove gather job contribution (creates global copy)
POST/pending-contributions/gather/{id}/rejectReject gather job contribution (clears flag)
POST/pending-contributions/helm-sync/{id}/approveApprove helm sync job contribution (creates global copy)
POST/pending-contributions/helm-sync/{id}/rejectReject helm sync job contribution (clears flag)
GET/eol-productsList EOL products with optional status filter
POST/eol-products/{id}/approveApprove EOL product for syncing
POST/eol-products/{id}/denyDeny EOL product from syncing (returns 409 if already approved)
POST/eol-sync/triggerTrigger an EOL sync run (returns 202, 409 if already running)
GET/eol-sync/historyList recent EOL sync runs
GET/usersList all users with superadmin status
GET/users/{id}/org-rolesGet cross-org role assignments for a user
POST/users/{id}/grant-superadminGrant superadmin role via Casbin g2
POST/users/{id}/revoke-superadminRevoke superadmin role (guards last superadmin)

Client UI Routes

The clientui binary serves HTML pages and forwards form submissions to the API. Routes are registered in internal/handlers/ui.go.

Auth Routes

When Supabase is configured (internal/handlers/auth.go, internal/handlers/onboarding.go):

MethodPathDescription
GET/loginLogin page (email/password + OAuth)
POST/auth/loginEmail/password login
GET/auth/signupSignup page
POST/auth/signupCreate account
GET/auth/login/:providerStart OAuth flow (PKCE)
GET/auth/callbackOAuth callback
GET/logoutSign out
GET/pending-approvalPending approval page (unapproved users)
GET/onboardingOnboarding page (new users)
POST/onboarding/create-orgCreate organization
POST/onboarding/accept-invite/:tokenAccept invite
POST/switch-orgSwitch active organization

Notification Channels UI

MethodPathDescription
GET/notification-channelsList channels page
POST/notification-channelsCreate channel (form submission)
GET/notification-channels/{id}Channel detail/edit page
POST/notification-channels/{id}Update channel (form submission)
POST/notification-channels/{id}/testTest channel and redirect with result
POST/notification-channels/{id}/toggleToggle active state
POST/notification-channels/{id}/deleteDelete channel

UI Error Handling

The clientui uses URL query parameters for error/success messages:

/notification-channels/1?error=Delivery+failed+with+HTTP+400
/notification-channels?success=Channel+created+successfully

Handlers format detailed API errors into user-friendly messages. See internal/handlers/notification_channels.go:formatTestErrorMessage() for the pattern.