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
| Topic | Rule |
|---|---|
| Authentication | On 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 requests | A 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. |
| Permission | Level on scope plus the action whose deny rule <scope>.<action>.deny withholds it. A deny rule wins over any level. See Access control. |
| Authenticated | A valid session is enough; the handler limits the call to the caller's own data. |
| Internal | Service token only (X-Service-Token). Not reachable through the dashboard proxy, which answers 404 for internal/ paths. Omitted below. |
| Unmapped route | 403. |
| Identity | Taken from the session. X-User-ID, X-Username and X-Email sent by a client are stripped. |
| Body keys | User, group, role, category and protection-plan writes refuse a key that is not exactly a field name of the record (400). |
| Body size | 413 above 1 MiB (exporter, auth, plan and rollback routes) or 64 KiB (analyzer). |
| Outage | 503 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | applications | exporter | ReadOnly on applications |
GET | applications/{name} | exporter | ReadOnly on applications |
PATCH | applications/{name} | exporter | Contributor on applications; editapplication. Display name and description only. |
POST | applications/{name}/sync | discovery | Contributor on applications; forceapplicationsync |
POST | applications/{name}/reset | discovery | Owner on applications; deleteapplication |
GET | discovery/status | discovery | ReadOnly on applications |
GET | cluster/namespaces | discovery | Authenticated; the handler requires ReadOnly on applications or on insights |
GET | cluster/namespaces/{namespace}/workloads | discovery | ReadOnly on applications |
GET | cluster/namespaces/{namespace}/resources | discovery | ReadOnly 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | applications/{name}/rollbacks | exporter | ReadOnly on applications; viewapplicationsrollbacks |
GET | applications/{name}/rollbacks/{rollbackId} | exporter | ReadOnly on applications; viewapplicationsrollbacks |
POST | applications/{name}/rollbacks | discovery | Contributor on applications; rollbackapplication |
POST | applications/{name}/rollbacks/{rollbackId}/abort | discovery | Contributor 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | snapshots | exporter | ReadOnly on applications; viewapplicationssnapshots. Volume usage and counts. |
GET | snapshots/{id}?scope=apps&namespace=<ns>&generation=<n> | exporter | ReadOnly on applications; viewapplicationssnapshots and viewapplicationsnapshotmanifest |
GET | snapshots/{id}/manifest?scope=apps&namespace=<ns>&generation=<n> | exporter | ReadOnly on applications; viewapplicationsnapshotmanifest. Accept: application/yaml for YAML, JSON otherwise. |
Secret data and stringData values are returned as [redacted].
Protection plans
| Method | Path | Service | Permission (on protection-plans) |
|---|---|---|---|
GET | protectionplans | exporter | ReadOnly; viewprotectionplans |
GET | protectionplans/{id} | exporter | ReadOnly; viewprotectionplans |
GET | policytemplates | discovery | ReadOnly; viewprotectionplans |
POST | protectionplans/prepare | discovery | Contributor; createprotectionplan |
POST | protectionplans/{id}/revise | discovery | Contributor; editprotectionplan |
POST | protectionplans/{id}/duplicate | discovery | Contributor; duplicateprotectionplan |
POST | protectionplans/{id}/cancel | discovery | Contributor; cancelprotectionplan |
POST | protectionplans/{id}/reactivate | discovery | Contributor; reactivateprotectionplan |
POST | protectionplans/{id}/decision | discovery | Owner; approveprotectionplan or rejectprotectionplan |
GET | protectionplans/{id}/status | discovery | ReadOnly; viewprotectionplans |
GET | protectionplans/{id}/violations?limit=<n>&result=<r> | discovery | ReadOnly; viewprotectionplanviolations |
DELETE | protectionplans/{id}/clear | discovery | Owner; deleteprotectionplan |
- Create and edit plans through discovery. The exporter's
POST protectionplansaccepts no lifecycle, approval or policy fields from a session, and itsPATCHandDELETEare Internal. decisionbody:{"decision": "approved" | "rejected", "comment": "…", "requestedAt": "<pending request>"}. A rejection needs a comment; a stalerequestedAtanswers409.enforceon anamespacesscope and a client-sentapprovalMode: automaticneed Owner.statuscomputes health on request and returnsplanId,phase,health, per-policypoliciesanddrift(missing,unexpected); it neither repairs nor stores.violations:limit50 by default, 200 at most;resultis one ofpass,fail,warn,error,skip.window=runlists the plan's whole run instead, read as its report reads it (the ledger plus the live events), withsince(when the run started) andtruncated. Each row carriesrequestedBy, the Kubernetes user who sent the request.clearremoves the plan's policies, then the plan and its reports.?keepReports=truekeeps the reports; a value that is not a boolean is refused (400) before anything is removed.
Reports
| Method | Path | Service | Permission (on protection-plans) |
|---|---|---|---|
POST | protectionplans/{id}/reports | discovery | Contributor; generateprotectionplanreport |
GET | protectionplans/{id}/reports | exporter | ReadOnly; viewprotectionplanreports |
GET | protectionplans/{id}/reports/download?report=<id>&format=<html|md|json|csv> | exporter | ReadOnly; downloadprotectionplanreport |
DELETE | protectionplans/{id}/reports?report=<id> | exporter | Owner; deleteprotectionplan. Deletes one report, of a live plan or a kept one. |
GET | reports?planId=<id>&trigger=<manual|cancel|end|window>&from=<RFC3339>&to=<RFC3339>&limit=<n> | exporter | ReadOnly; viewprotectionplanreports |
GET | reports/kept | exporter | ReadOnly; 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | insights | discovery | ReadOnly on insights |
GET | insights/applications?apps=<ns>/<name>,… | discovery | ReadOnly on insights. At most 100 applications. |
POST | insights/applications/{namespace}/{name}/analyze | analyzer | Contributor on insights; analyzeinsights |
POST | insights/applications/{namespace}/{name}/insights/{id}/triage | analyzer | Contributor on insights; triageinsights |
GET | insights/events?apps=<ns>/<name>,… | analyzer | ReadOnly on insights, or Owner on settings. Server-sent events. |
GET | insights/runtime | analyzer | ReadOnly on insights, or Owner on settings |
POST | insights/runtime/validate | analyzer | Owner on settings; controlainsights |
POST | insights/runtime/pull | analyzer | Owner 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | users, users/{id} | exporter | ReadOnly on users; your own users/{id} needs only a session. Administrators are visible only to Admin on ALL. |
GET | users/names?ids=a,b | exporter | Authenticated. 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. |
POST | users | exporter | Contributor on users; createuser, plus the rights of any privileged field set |
PATCH | users/{id} | exporter | Authenticated: your own profile, or the rights of each privileged field changed (roles, groups, status) |
DELETE | auth/users/{id} | auth | Owner on users; deleteuser. Ends the user's sessions and removes references. |
POST | auth/users/{id}/enroll-link | auth | Owner on users, plus the enrollment-link rules below. 201 with {token, expiresAt}; the token appears only in this answer. |
DELETE | auth/users/{id}/enroll-link | auth | Owner on users, plus the enrollment-link rules below. Revokes the pending link. |
GET | groups, groups/{id} | exporter | ReadOnly on groups |
POST | groups | exporter | Contributor on groups; creategroup |
PATCH | groups/{id} | exporter | Contributor on groups; editgroup, plus the member and role rules |
DELETE | auth/groups/{id} | auth | Owner on groups; deletegroup |
GET | accessroles, accessroles/{id} | exporter | ReadOnly on roles |
POST | accessroles | exporter | Contributor on roles; createrole |
PATCH | accessroles/{id} | exporter | Contributor on roles; editrole |
DELETE | auth/accessroles/{id} | auth | Owner 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | categories?scope=<scope>, categories/{id} | exporter | Authenticated |
POST | categories | exporter | Authenticated; the category rules of its scope (add…category) |
PATCH | categories/{id} | exporter | Authenticated; edit…category of its scope |
DELETE | categories/{id} | exporter | Authenticated; 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | config | exporter | ReadOnly on settings. The TelarkConfig, with the pinned Google key set merged in. |
PATCH | config | exporter | Per field: see below |
GET | bootstrap | exporter | Admin on ALL. The pinned bootstrap account, its break-glass recovery requests, and notifyAdmins. While notifyAdmins is false, only the bootstrap account gets the requests. |
PATCH | auth/oidc/config | auth | The bootstrap account only; editoidcconfig |
PATCH | auth/self-registration | auth | The bootstrap account only. Body {"enabled": true | false}. |
PATCH | auth/break-glass-alerts | auth | The bootstrap account only. Body {"notifyAdmins": true | false}. |
GET | cleanup/{type}, cleanup/{type}/{id} | exporter | ReadOnly on settings. Deletion-cleanup state. |
PUT, DELETE | cleanup/{type}/{id}/finalizer | exporter | Owner on settings |
config field | Permission |
|---|---|
excludedNamespaces | Contributor on settings; editdiscoveryconfig |
snapshots | Contributor on settings; editsnapshotstorage |
ai | Owner on settings; controlainsights |
oidc, selfRegistration, breakGlassAlerts | Internal. Change them through auth/oidc/config, auth/self-registration and auth/break-glass-alerts. |
cluster | Internal |
bootstrap | Refused. 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
| Method | Path | Service | Permission |
|---|---|---|---|
GET | auth/config | auth | Public. Sign-in options: selfRegistrationEnabled, oidcEnabled, and googleClientID while Google sign-in is usable. |
POST | auth/register/start | auth | Public. A bare email, with no session or enrollment token, works only while self-registration is on. |
POST | auth/passkeys | auth | Public for the registration register/start opened; a session to add a passkey to your account |
POST | auth/login/start | auth | Public |
POST | auth/login/finish | auth | Public. Sets the session cookie; the body carries no token. |
POST | auth/oidc/google/nonce | auth | Public |
POST | auth/oidc/google/callback | auth | Public. Sets the session cookie, with no token in the body; 503 when Google sign-in is not configured. |
POST | auth/logout | auth | Public. Deletes the session named by the token sent and clears the cookie. |
POST | auth/bootstrap/requests/{id}/assert/start, …/finish | auth | Public. 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. |
GET | auth/permissions | auth | Authenticated. Your roles, each with its {scope, level, rules} entries. |
GET | auth/passkeys, auth/passkeys/{credentialId} | auth | Authenticated, your own |
PATCH, DELETE | auth/passkeys/{credentialId} | auth | Authenticated, your own |
POST | auth/passkeys/enroll-link | auth | Authenticated. A one-time link, valid 10 minutes, for your own account. |
GET | auth/sessions?user=<id>, auth/sessions/self | exporter | Authenticated, your own |
DELETE | auth/sessions/self, auth/sessions/{name} | exporter | Authenticated, your own. {name} is session-<sha256>; a raw token in the path is refused. |
Notifications
| Method | Path | Service | Permission |
|---|---|---|---|
GET | notifications?userId=<id>&limit=<n>&cursor=<c> | exporter | Authenticated, your own. limit 50 by default, 200 at most. |
GET | notifications/events | exporter | Authenticated, 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. |
POST | notifications/{id}/read?userId=<id> | exporter | Authenticated, your own |
POST | notifications/read?userId=<id> | exporter | Authenticated, your own. Marks all read. |
DELETE | notifications?userId=<id> | exporter | Authenticated, your own. Clears all. |
DELETE | notifications/{id}?userId=<id> | exporter | Authenticated, 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.
Related
- CRD reference for the shape of every record
- Access control