Probe Polaris health.

• live: process liveness (no dependencies; use for restart probes)

• ready: readiness to serve traffic (verifies PostgreSQL; 503 problem document while down)

Returns {"status": "ok"} on success.

Manage Polaris tribes, the topology level that groups squads.

Actions and required parameters:

• list: optional limit (1-200) / cursor / all_pages

• get: tribe_id

• create: name (optional description)

• archive: tribe_id (optional reason) — tribe stays queryable, status becomes ARCHIVED

• overview: tribe_id — aggregated tribe fitness overview (Insights read model)

Tribe JSON: {id, kind: "tribe", status: ACTIVE|ARCHIVED, revision, data: {name, description?}, createdAt, updatedAt}. Lists return {items, nextCursor}; pass nextCursor back as cursor.

Manage squads, the owning unit of fitness targets, sources, producers, and fitness functions.

Actions and required parameters:

• list: tribe_id — squads currently in the tribe (optional limit/cursor/all_pages)

• get: squad_id

• create: tribe_id + name (optional mission) — squad is registered ACTIVE in the tribe

• transfer: squad_id + destination_tribe_id (optional reason) — squad keeps ownership of everything it owns

Squad JSON: {id, parentId: tribeId, kind: "squad", status: ACTIVE, revision, data: {name, mission?}, createdAt, updatedAt}.

Manage fitness targets: systems (services, databases, queues, ...) a squad is accountable for.

Actions and required parameters:

• list: squad_id (optional limit/cursor/all_pages)

• get: target_id

• create: squad_id + name (optional description, target_kind e.g. SERVICE/DATABASE/QUEUE, criticality e.g. CRITICAL/HIGH, external_reference object) — created ACTIVE

• transition: target_id + status (ACTIVE|DEPRECATED|RETIRED, optional reason) — explicit, auditable lifecycle change; history stays queryable

• history: target_id — chronological fitness-history entries (Insights read model)

Target JSON: {id, parentId: squadId, kind: "fitness-target", status: ACTIVE|DEPRECATED|RETIRED, revision, data: {name, description?, kind?, criticality?, externalReference?}, ...}.

Discover supported pull measurement providers.

Action: list_types — returns the provider capability catalog. Each entry states the query capabilities (INSTANT_QUERY, RANGE_QUERY) and supported outbound authentication modes (only NONE in v1; only PROMETHEUS is supported). Use this instead of hard-coding provider assumptions; new providers appear here without changing other resource shapes.

Manage measurement sources: squad-owned connections to pull providers.

Lifecycle: create → DRAFT, then check_connection must succeed, then activate. Retirement is rejected (409) while an active fitness-function version still depends on the source.

Actions and required parameters:

• list: squad_id (optional limit/cursor/all_pages)

• get: source_id

• create: squad_id + name + provider_type (PROMETHEUS) + base_url (optional description). Never include credentials; none are stored or returned. Created in DRAFT.

• check_connection: source_id — probes the provider; retained as evidence. A failed probe yields 422 with the provider error in the detail.

• validate_query: source_id + query (a MetricQuery object; optional execute_sample=true also executes it once and returns the sample value with provider evidence). Query keys (camelCase): criterionKey, expression (PromQL), mode (INSTANT|RANGE), reduction (LAST|MIN|MAX|AVERAGE|SUM|COUNT), seriesPolicy (REQUIRE_SINGLE_SERIES|REDUCE_ACROSS_SERIES| ERROR_ON_MULTIPLE_SERIES), unit, plus lookbackSeconds/stepSeconds for RANGE.

• activate: source_id (optional reason, e.g. which check id was reviewed)

• retire: source_id (optional reason)

Source JSON: {id, parentId: squadId, kind: "measurement-source", status: DRAFT|ACTIVE|RETIRED, revision, data: {name, providerType, baseUrl, description?}, ...}.

Register measurement producers: identities authorized to PUSH measurements for a squad.

Action: create — requires squad_id + name (optional description). A push fitness-function definition declares exactly one producerId, and only that producer may submit against it.

Producer JSON: {id, parentId: squadId, kind: "measurement-producer", status: ACTIVE, revision, data: {name, description?}, ...}. The returned id is the producerId to reference in PUSH acquisition definitions and submissions.

Manage fitness functions: versioned definitions of intent, scope, criteria, acquisition, freshness, and enforcement. Definitions evolve as immutable draft-then-activate versions.

Actions and required parameters:

• list: squad_id — the squad's functions with full version history (limit/cursor/all_pages)

• get: fitness_function_id — aggregate with lifecycle (DRAFT|ACTIVE|RETIRED), revision, and complete version history

• create: squad_id + definition — creates the function with draft version 1

• add_version: fitness_function_id + definition — appends a new draft version (guarded by If-Match: pass the aggregate revision explicitly, or omit it to use the current one)

• update_draft_version: fitness_function_id + version + definition — replaces a still-DRAFT version (If-Match as above; activated versions are immutable)

• validate_version: fitness_function_id + version — re-runs validation without side effects

• activate_version: fitness_function_id + version (optional reason) — makes it the active definition; evaluations then use it

• retire: fitness_function_id (optional reason) — terminal; history stays queryable

definition is a JSON object with camelCase keys (Polaris FitnessDefinition): required: name; purpose; objective; targetIds (array of the squad's fitness-target ids); criteria (array of {key (pattern ^[a-z][a-z0-9_]{0,62}$, unit, warningComparison?, warningValue?, failureComparison (GREATER_THAN|GREATER_THAN_OR_EQUAL|LESS_THAN|LESS_THAN_OR_EQUAL| EQUAL|NOT_EQUAL), failureValue, required?}); acquisition ({mode: "PUSH", producerId, maximumObservationAgeSeconds} or {mode: "PULL", sourceId, trigger: SCHEDULED|ON_DEMAND, intervalSeconds? (>=60, SCHEDULED only), timeoutSeconds (1-30), queries: array of {criterionKey, expression (PromQL), mode: INSTANT|RANGE, lookbackSeconds?, stepSeconds?, reduction (LAST|MIN|MAX|AVERAGE|SUM|COUNT), seriesPolicy (REQUIRE_SINGLE_SERIES|REDUCE_ACROSS_SERIES|ERROR_ON_MULTIPLE_SERIES), unit} covering every criterion key}); freshnessSeconds (how long an evaluation stays fresh); enforcement (OBSERVE|WARN|BLOCK); optional: characteristic (e.g. RELIABILITY), changeRationale. Warning thresholds must be milder than failure thresholds when both are declared.

Push measurements for evaluation against the ACTIVE fitness-function version.

These are the ingest endpoints: they authenticate with the X-API-Key configured as POLARIS_INGEST_API_KEY (no Google login involved).

Actions and required parameters:

• submit: fitness_function_id + submission — evaluates synchronously and returns the recorded evaluation (with replayed: true when a duplicate producerId+externalRunId delivery returned the original evaluation). Submissions against a non-active version yield 409.

• submit_batch: items — up to 100 independent submissions, each {fitnessFunctionId, submission}; the 207 response carries per-item status (201 success, or 404/409/422/500 with an error message); per-item failures do not abort the batch.

submission is a JSON object with camelCase keys: required: fitnessFunctionVersion (the active version number); producerId (the producer declared by the active definition); externalRunId (producer-scoped run id, the idempotency natural key); observedAt (RFC 3339 UTC, not in the future, within the definition's maximum observation age); measurements (array of {criterionKey, value, unit, observedAt?}, one per criterion, duplicates rejected); optional: evaluationRequestId (request this submission fulfills), evidence (array of arbitrary evidence documents).

Manage evaluation requests.

Actions and required parameters:

• create: fitness_function_id — accepted with 202 as PENDING; fulfilled when a producer pushes a submission carrying the request's id (or by pull collection)

• get: request_id — poll the state (PENDING until fulfilled, CANCELLED after cancellation)

• cancel: request_id — cancels a PENDING request (e.g. the triggering pipeline was aborted); cancelling twice yields 409

Evaluation-request JSON: {id, parentId: fitnessFunctionId, kind: "evaluation-request", status: PENDING|CANCELLED, revision, data, createdAt, updatedAt}. The created id is the evaluationRequestId a producer references in its submission.

Read evaluations.

Actions and required parameters:

• get: evaluation_id — the immutable evaluation in full

• list_by_function: fitness_function_id — recorded evaluations in creation order (optional limit/cursor/all_pages)

Evaluation JSON: {evaluationId, fitnessFunctionId, fitnessFunctionVersion, acquisitionMode: PUSH|PULL, originId, outcome: PASS|WARN|FAIL|ERROR|NOT_APPLICABLE, disposition: ACCEPTED|ATTENTION_REQUIRED|BLOCKED|WAIVED (enforcement decision honoring approved unexpired waivers), observedAt, validUntil (stale after this), criterionResults: [{criterionKey, value, unit, outcome: PASS|WARN|FAIL}], data: retained measurements and evidence}. Evaluations are never modified after recording; no data never counts as success.

Manage pull collection attempts.

Actions and required parameters:

• list: fitness_function_id — retained attempts with measurements and provider evidence

• get: attempt_id — one retained attempt (status SUCCEEDED|FAILED, measurements, evidence)

• collect_now: fitness_function_id — executes the active PULL definition immediately (outside its schedule) and returns the recorded evaluation. Requires an ACTIVE function with a PULL acquisition and an ACTIVE source; provider failures surface as 500.

• retry: attempt_id — re-runs collection after e.g. a provider outage; returns the new evaluation while the original attempt is retained unchanged

Attempt JSON: {id, parentId: fitnessFunctionId, kind: "collection-attempt", status: SUCCEEDED|FAILED, revision, data: {sourceId, measurements: [{criterionKey, value, unit}], evidence: [...]}, createdAt, updatedAt}.

Manage waivers: explicit, justified, time-limited exceptions for failing criteria.

Actions and required parameters:

• propose: fitness_function_id + reason (why the exception is temporarily acceptable); optional criterion_keys (failing criteria covered; omit for all), risk, compensating_action, starts_at / expires_at (RFC 3339; expiresAt must be in the future and after startsAt). Enters state PROPOSED; only takes effect on approval.

• decide: waiver_id + decision (approve|reject|revoke, optional reason). Approving accepts the risk (the waiver then influences dispositions until it expires); rejecting declines the proposal; revoking ends an approved waiver early. Deciding twice yields 409.

Waiver JSON: {id, parentId: fitnessFunctionId, kind: "waiver", status: PROPOSED|APPROVED| REJECTED|REVOKED, revision, data: {reason, criterionKeys?, risk?, compensatingAction?, startsAt?, expiresAt?}, createdAt, updatedAt}. Only APPROVED, unexpired waivers influence dispositions.

Manage tribe-published fitness-function templates.

Actions and required parameters:

• list: tribe_id — the tribe's templates (optional limit/cursor/all_pages)

• publish: tribe_id + name (optional description, optional definition — a FitnessDefinition object with the same camelCase keys used by polaris_fitness_functions). Names are unique within a tribe (duplicate yields 409).

• adopt: template_id + squad_id (optional target_ids scope override, optional reason) — creates a squad-owned DRAFT fitness function; the tribe retains no ownership, and the squad may adapt the draft before activating it.

Template JSON: {id, parentId: tribeId, kind: "fitness-function-template", status: ACTIVE, revision, data: {name, description?, definition?}, createdAt, updatedAt}.

Read insight aggregates computed from retained evaluations.

Actions and required parameters:

• squad_overview: squad_id — aggregated architectural fitness for one squad

• tribe_overview: tribe_id — patterns across the tribe's squads (no league table)

• target_history: target_id — chronological fitness-history entries for one target (optional limit/cursor/all_pages)

Overviews expose outcomes and dispositions without collapsing them into a single universal score: {scope: squad|tribe, scopeId, generatedAt, status: AVAILABLE}.

Consume delivery events published through the transactional outbox.

Actions and required parameters:

• poll: consumer_id (stable identity, 1-100 chars) — returns events newer than cursor (optional limit). Persist the returned nextCursor between polls; without a cursor you start from the oldest event. After successfully processing events, acknowledge them.

• acknowledge: consumer_id + event_ids (1-500 ids) — acknowledged events are never redelivered to that consumer; acknowledgement is idempotent per (consumer, event) pair.

Event JSON: {id, type (e.g. EvaluationRecorded, FitnessFunctionVersionActivated), version, aggregateType, aggregateId, occurredAt, actor, correlationId, payload}.