Reference

API reference

Every user-facing REST route of the Telark services, grouped by resource, with the permission each one needs.

Each service serves its API under /api/v1/. The dashboard proxies them on its own origin at /api/<service>/, so discovery's protectionplans/prepare is /api/discovery/api/v1/protectionplans/prepare from the browser. Paths below are relative to /api/v1/.

Conventions

TopicRule
AuthenticationOn every route except the Public ones: the session cookie the dashboard holds (__Host-telark_session when every app.auth.passkey.origin entry is https://, else telark_session), or X-Session-Token: <token> from API clients. The header wins over the cookie. Never a query parameter.
Cookie requestsA change (any method but GET, HEAD and OPTIONS) sent with neither X-Session-Token nor X-Service-Token needs an X-Requested-With header, Public routes included, else 403 with the code csrf_header_missing. Two session cookies count as none: a route that needs a session answers 401 with the code session_cookie_duplicate, while Public routes such as logout still run.
PermissionLevel on scope plus the action whose deny rule <scope>.<action>.deny withholds it. A deny rule wins over any level. See Access control.
AuthenticatedA valid session is enough; the handler limits the call to the caller's own data.
InternalService token only (X-Service-Token). Not reachable through the dashboard proxy, which answers 404 for internal/ paths. Omitted below.
Unmapped route403.
IdentityTaken from the session. X-User-ID, X-Username and X-Email sent by a client are stripped.
Body keysUser, group, role, category and protection-plan writes refuse a key that is not exactly a field name of the record (400).
Body size413 above 1 MiB (exporter, auth, plan and rollback routes) or 64 KiB (analyzer).
Outage503 when a service cannot resolve the caller, never a denial or a grant.
Response{status, operation, message, data}. Reads return id from metadata.name and flatten .status into the object.

Applications

MethodPathServicePermission
GETapplicationsexporterReadOnly on applications
GETapplications/{name}exporterReadOnly on applications
PATCHapplications/{name}exporterContributor on applications; editapplication. Display name and description only.
POSTapplications/{name}/syncdiscoveryContributor on applications; forceapplicationsync
POSTapplications/{name}/resetdiscoveryOwner on applications; deleteapplication
GETdiscovery/statusdiscoveryReadOnly on applications
GETcluster/namespacesdiscoveryAuthenticated; the handler requires ReadOnly on applications or on insights
GETcluster/namespaces/{namespace}/workloadsdiscoveryReadOnly on applications
GETcluster/namespaces/{namespace}/resourcesdiscoveryReadOnly on applications

sync and reset answer 404 for an application Telark does not hold. The cluster/namespaces routes refuse excluded namespaces and the release namespace (403).

Rollbacks

MethodPathServicePermission
GETapplications/{name}/rollbacksexporterReadOnly on applications; viewapplicationsrollbacks
GETapplications/{name}/rollbacks/{rollbackId}exporterReadOnly on applications; viewapplicationsrollbacks
POSTapplications/{name}/rollbacksdiscoveryContributor on applications; rollbackapplication
POSTapplications/{name}/rollbacks/{rollbackId}/abortdiscoveryContributor on applications; rollbackapplication

Trigger body: {"snapshotGeneration": <n>}. 409 while another rollback of the application is pending or in progress; abort answers 409 unless the entry is pending.

Snapshots

MethodPathServicePermission
GETsnapshotsexporterReadOnly on applications; viewapplicationssnapshots. Volume usage and counts.
GETsnapshots/{id}?scope=apps&namespace=<ns>&generation=<n>exporterReadOnly on applications; viewapplicationssnapshots and viewapplicationsnapshotmanifest
GETsnapshots/{id}/manifest?scope=apps&namespace=<ns>&generation=<n>exporterReadOnly on applications; viewapplicationsnapshotmanifest. Accept: application/yaml for YAML, JSON otherwise.

Secret data and stringData values are returned as [redacted].

Protection plans

MethodPathServicePermission (on protection-plans)
GETprotectionplansexporterReadOnly; viewprotectionplans
GETprotectionplans/{id}exporterReadOnly; viewprotectionplans
GETpolicytemplatesdiscoveryReadOnly; viewprotectionplans
POSTprotectionplans/preparediscoveryContributor; createprotectionplan
POSTprotectionplans/{id}/revisediscoveryContributor; editprotectionplan
POSTprotectionplans/{id}/duplicatediscoveryContributor; duplicateprotectionplan
POSTprotectionplans/{id}/canceldiscoveryContributor; cancelprotectionplan
POSTprotectionplans/{id}/reactivatediscoveryContributor; reactivateprotectionplan
POSTprotectionplans/{id}/decisiondiscoveryOwner; approveprotectionplan or rejectprotectionplan
GETprotectionplans/{id}/statusdiscoveryReadOnly; viewprotectionplans
GETprotectionplans/{id}/violations?limit=<n>&result=<r>discoveryReadOnly; viewprotectionplanviolations
DELETEprotectionplans/{id}/cleardiscoveryOwner; deleteprotectionplan
  • Create and edit plans through discovery. The exporter's POST protectionplans accepts no lifecycle, approval or policy fields from a session, and its PATCH and DELETE are Internal.
  • decision body: {"decision": "approved" | "rejected", "comment": "…", "requestedAt": "<pending request>"}. A rejection needs a comment; a stale requestedAt answers 409.
  • enforce on a namespaces scope and a client-sent approvalMode: automatic need Owner.
  • status computes health on request and returns planId, phase, health, per-policy policies and drift (missing, unexpected); it neither repairs nor stores.
  • violations: limit 50 by default, 200 at most; result is one of pass, fail, warn, error, skip. window=run lists the plan's whole run instead, read as its report reads it (the ledger plus the live events), with since (when the run started) and truncated. Each row carries requestedBy, the Kubernetes user who sent the request.
  • clear removes the plan's policies, then the plan and its reports. ?keepReports=true keeps the reports; a value that is not a boolean is refused (400) before anything is removed.

Reports

MethodPathServicePermission (on protection-plans)
POSTprotectionplans/{id}/reportsdiscoveryContributor; generateprotectionplanreport
GETprotectionplans/{id}/reportsexporterReadOnly; viewprotectionplanreports
GETprotectionplans/{id}/reports/download?report=<id>&format=<html|md|json|csv>exporterReadOnly; downloadprotectionplanreport
DELETEprotectionplans/{id}/reports?report=<id>exporterOwner; deleteprotectionplan. Deletes one report, of a live plan or a kept one.
GETreports?planId=<id>&trigger=<manual|cancel|end|window>&from=<RFC3339>&to=<RFC3339>&limit=<n>exporterReadOnly; viewprotectionplanreports
GETreports/keptexporterReadOnly; viewprotectionplanreports. The reports that plan deletes kept, one entry per deleted plan with its name.

Generating answers 400 for a plan that never started and 429 with Retry-After while two renders run. The cross-plan list defaults to 200 rows (1,000 at most); planId repeats or takes a comma list, and X-Total-Count holds the match count before the limit. The download and delete routes serve kept reports too.

Insights

MethodPathServicePermission
GETinsightsdiscoveryReadOnly on insights
GETinsights/applications?apps=<ns>/<name>,…discoveryReadOnly on insights. At most 100 applications.
POSTinsights/applications/{namespace}/{name}/analyzeanalyzerContributor on insights; analyzeinsights
POSTinsights/applications/{namespace}/{name}/insights/{id}/triageanalyzerContributor on insights; triageinsights
GETinsights/events?apps=<ns>/<name>,…analyzerReadOnly on insights, or Owner on settings. Server-sent events.
GETinsights/runtimeanalyzerReadOnly on insights, or Owner on settings
POSTinsights/runtime/validateanalyzerOwner on settings; controlainsights
POSTinsights/runtime/pullanalyzerOwner on settings; controlainsights

GET insights query parameters. category (incident, recommendation); kind, severity, state (open, updated, resolved, stale) and namespace, each a comma list; triage (untriaged, acknowledged, dismissed, all); environment (a plan environment id); q (text search); id and app (<namespace>/<name>), comma lists; page (from 1); pageSize (1–100, default 25); fresh=true to include every write acknowledged before the request. Without state it returns open, updated and stale cards; without triage it hides dismissed ones. The response holds items, total, page, pageSize, counts and indexedAt, with an ETag for If-None-Match. It answers 503 with Retry-After: 5 until the index has loaded.

Triage body. {"action": "acknowledge" | "dismiss" | "reopen"}. dismiss applies to recommendations only. 404 for an unknown card, 409 for an action the card cannot take in its state.

Analyzer limits. Manual analyze answers 429 when more than 100 jobs are queued. A user holds at most 8 event streams (429 beyond); each stream re-checks the session every minute. In deep mode, analyze answers 503 unless the runtime is ready. Pull answers 409 when auto-pull is off and 400 for a model outside the license catalog.

Users, groups and roles

MethodPathServicePermission
GETusers, users/{id}exporterReadOnly on users; your own users/{id} needs only a session. Administrators are visible only to Admin on ALL.
GETusers/names?ids=a,bexporterAuthenticated. Returns only id → username, for up to 100 ids; unknown ids are left out. Names every account, administrators included, so audit fields show who acted.
POSTusersexporterContributor on users; createuser, plus the rights of any privileged field set
PATCHusers/{id}exporterAuthenticated: your own profile, or the rights of each privileged field changed (roles, groups, status)
DELETEauth/users/{id}authOwner on users; deleteuser. Ends the user's sessions and removes references.
POSTauth/users/{id}/enroll-linkauthOwner on users, plus the enrollment-link rules below. 201 with {token, expiresAt}; the token appears only in this answer.
DELETEauth/users/{id}/enroll-linkauthOwner on users, plus the enrollment-link rules below. Revokes the pending link.
GETgroups, groups/{id}exporterReadOnly on groups
POSTgroupsexporterContributor on groups; creategroup
PATCHgroups/{id}exporterContributor on groups; editgroup, plus the member and role rules
DELETEauth/groups/{id}authOwner on groups; deletegroup
GETaccessroles, accessroles/{id}exporterReadOnly on roles
POSTaccessrolesexporterContributor on roles; createrole
PATCHaccessroles/{id}exporterContributor on roles; editrole
DELETEauth/accessroles/{id}authOwner on roles; deleterole

The dashboard deletes through auth, which also removes every reference to the record. The exporter serves DELETE users/{id}, groups/{id} and accessroles/{id} with the same permissions.

Privileged fields: adding or removing roles needs Owner on users (attachroletouser, removerolefromuser); groups need Owner on groups (addusertogroup, removeuserfromgroup); account status needs Admin on users (suspenduser). A role may not be granted above the caller's own level, and nobody edits their own roles, groups or status.

Enrollment links: every level the target holds, directly or through a group, must be within the caller's own (403). Both routes refuse your own account and the bootstrap account (403); creating also refuses a suspended account (409) and one being deleted (410). An administrator or the bootstrap account answers 404 to a caller below Admin on ALL. A link for an account that already has a passkey needs the bootstrap account or Admin on ALL. A new link revokes the previous one.

Categories

MethodPathServicePermission
GETcategories?scope=<scope>, categories/{id}exporterAuthenticated
POSTcategoriesexporterAuthenticated; the category rules of its scope (add…category)
PATCHcategories/{id}exporterAuthenticated; edit…category of its scope
DELETEcategories/{id}exporterAuthenticated; delete…category of its scope

Scopes: groups, roles, plan-environments, plan-tags, plan-kinds. A DELETE of a category that a group, role or protection plan still uses is refused with 409, and the message gives the count.

Settings

MethodPathServicePermission
GETconfigexporterReadOnly on settings. The TelarkConfig, with the pinned Google key set merged in.
PATCHconfigexporterPer field: see below
GETbootstrapexporterAdmin on ALL. The pinned bootstrap account, its break-glass recovery requests, and notifyAdmins. While notifyAdmins is false, only the bootstrap account gets the requests.
PATCHauth/oidc/configauthThe bootstrap account only; editoidcconfig
PATCHauth/self-registrationauthThe bootstrap account only. Body {"enabled": true | false}.
PATCHauth/break-glass-alertsauthThe bootstrap account only. Body {"notifyAdmins": true | false}.
GETcleanup/{type}, cleanup/{type}/{id}exporterReadOnly on settings. Deletion-cleanup state.
PUT, DELETEcleanup/{type}/{id}/finalizerexporterOwner on settings
config fieldPermission
excludedNamespacesContributor on settings; editdiscoveryconfig
snapshotsContributor on settings; editsnapshotstorage
aiOwner on settings; controlainsights
oidc, selfRegistration, breakGlassAlertsInternal. Change them through auth/oidc/config, auth/self-registration and auth/break-glass-alerts.
clusterInternal
bootstrapRefused. Only the exporter writes the pin and the requests.

The two auth routes refuse every other account (403), Admins on ALL included: auth reads the bootstrap marker from the caller's own user record, not from its grants.

Sign-in and sessions

MethodPathServicePermission
GETauth/configauthPublic. Sign-in options: selfRegistrationEnabled, oidcEnabled, and googleClientID while Google sign-in is usable.
POSTauth/register/startauthPublic. A bare email, with no session or enrollment token, works only while self-registration is on.
POSTauth/passkeysauthPublic for the registration register/start opened; a session to add a passkey to your account
POSTauth/login/startauthPublic
POSTauth/login/finishauthPublic. Sets the session cookie; the body carries no token.
POSTauth/oidc/google/nonceauthPublic
POSTauth/oidc/google/callbackauthPublic. Sets the session cookie, with no token in the body; 503 when Google sign-in is not configured.
POSTauth/logoutauthPublic. Deletes the session named by the token sent and clears the cookie.
POSTauth/bootstrap/requests/{id}/assert/start, …/finishauthPublic. Approves or denies a break-glass recovery request (action approve or deny) with a user-verified passkey of the pinned bootstrap account. Needs no session and creates none. approve answers 409 for a recovery, which can only be denied, and deny answers 409 while a break-glass run is recovering the account.
GETauth/permissionsauthAuthenticated. Your roles, each with its {scope, level, rules} entries.
GETauth/passkeys, auth/passkeys/{credentialId}authAuthenticated, your own
PATCH, DELETEauth/passkeys/{credentialId}authAuthenticated, your own
POSTauth/passkeys/enroll-linkauthAuthenticated. A one-time link, valid 10 minutes, for your own account.
GETauth/sessions?user=<id>, auth/sessions/selfexporterAuthenticated, your own
DELETEauth/sessions/self, auth/sessions/{name}exporterAuthenticated, your own. {name} is session-<sha256>; a raw token in the path is refused.

Notifications

MethodPathServicePermission
GETnotifications?userId=<id>&limit=<n>&cursor=<c>exporterAuthenticated, your own. limit 50 by default, 200 at most.
GETnotifications/eventsexporterAuthenticated, your own. Server-sent events: event: changed after each change to your list (refetch it), and : ping every 15 seconds. At most 8 streams per user (429 beyond); the session is re-checked every 60 seconds.
POSTnotifications/{id}/read?userId=<id>exporterAuthenticated, your own
POSTnotifications/read?userId=<id>exporterAuthenticated, your own. Marks all read.
DELETEnotifications?userId=<id>exporterAuthenticated, your own. Clears all.
DELETEnotifications/{id}?userId=<id>exporterAuthenticated, your own. Deletes one.

userId must be the caller's own id (403 otherwise). An unknown id, or someone else's, answers 404 on the single-notification routes. The list returns items, unreadCount and nextCursor.

Health probes

GET status/live and GET status/ready are Public on every service (auth also serves status/health). See Health checks for what each service checks.