Skip to main content

​
Management API

Use a user-scoped cli_ token for app discovery and creation. App-scoped admin_ keys can manage resources only within their app on routes that accept app authority; they cannot list or create apps. The CLI wraps management routes with target resolution, strict DTO validation, machine-readable errors, CAS, idempotency, plan integrity, and recovery. Prefer it for agent and CI workflows unless you need direct HTTP integration.

​
Apps and environments

The list response includes strict app and environment DTOs. App creation is a one-time secret-delivery operation and requires a caller idempotency key. It creates dev, staging, and prod environments, their environment keys, and an app-admin key. An identical retry can recover the same response during the delivery window.

​
Flags

The PATCH route supports create, update, upsert, toggle, value, rollout, variant, and legacy client-visibility changes. New flags require a type and value. Rollout and variants are mutually exclusive.

​
Atomic bulk apply

PATCH /api/v1/flags/bulk applies compatible existing legacy values, advanced configuration, and privacy changes in one transaction:
The operation uses atomic compare-and-swap. Success returns the new version, stable change ID, before/after versions, and whether the response was an idempotent replay. It cannot create/delete legacy flags or atomically change their legacy metadata.

​
Keys and one-time delivery

List responses never contain plaintext secrets. HTTP creation requires a caller-stable idempotency key and returns the plaintext token only in the one-time response; the CLI separately requires --show-secrets as an explicit display acknowledgement. Revoke keys by immutable ID.

​
Operational change journal

GET /api/v1/changes?appId=<id>&env=<slug> returns newest-first applied changes. Filter by exact change ID, operation, source, resource type/ID, safe authority metadata, time range, and bounded limit. Entries include redacted structured diffs and before/after versions; raw credentials and request payloads are never returned.

​
Metrics and experiments

Versioned metric endpoints live under /api/v1/metrics; experiment endpoints live under /api/v1/experiments. Definitions and running iterations reference immutable revisions. Creation relies on uniqueness and caller-stable idempotency. Revision, lifecycle, ramp, and update mutations additionally require the current revision/version precondition. The live OpenAPI document includes delivery, evaluation, telemetry ingestion, atomic bulk apply, OFREP, metrics, experiments, rollbacks, and change-journal operations. Some management responses are description-only rather than complete machine schemas. Use superflag contract --json and the CLI’s validated plan documents as the exact agent-facing source for current safe workflows.

​
Experiment results and bounded insights

Result reads pin an exact experiment iteration and return sufficient statistics, fixed-horizon intervals, readiness, health reason codes, freshness, and bounded operational diagnostics. They never declare a winner. Recompute requires confirm: true and caller idempotency; it fails closed when retained raw input cannot prove a safe replay. Aggregate insights are served from an asynchronous hourly read model, not the config or ingestion path. Requests are limited to 90 days, three allow-listed dimensions, ten measures, 1,000 rows, and 10,000 scanned buckets. Requests over 24 hours require a flag or experiment filter. Event-like reads are redacted, limited to seven days and 100 rows per opaque cursor page. Responses include schema/engine versions, requested/effective windows, watermark/freshness, query cost, approximation metadata, minimum-cell suppression, and rate-limit state. Cells below 20 approximate subjects return null measures. The API does not expose raw subjects, targeting context, arbitrary attributes, SQL, profiles, funnels, or cohorts. In schema v1, event source is app/environment provenance, not an evaluation origin or cache-state field. Insight queries therefore do not expose it as a source-rate dimension or infer error/fallback rates from free-form reasons. Those classifications require a future versioned telemetry contract.

​
Feature telemetry ingestion

POST /api/v1/events/batch accepts 1–100 canonical version-1 feature events from an environment sdk_ or pub_ key. Responses preserve order and report accepted, duplicate, permanent-error, or retryable-error status per item. Retry only retryable items with the same event IDs. Telemetry rate limiting and accounting are separate from configuration syncs. Public-key ingestion is restricted to client-visible resources and never becomes trusted management authority.

​
Subject erasure

POST /api/v1/telemetry/erasures requires a cli_ token or app-scoped admin_ key and accepts appId, env, namespace: "targetingKey", and the original subjectId. It returns 202 with a non-identifying receipt; it never returns the subject or derived references. Poll that receipt with GET /api/v1/telemetry/erasures?appId=<id>&env=<slug>&id=<receipt-id>. Erasure is bounded and asynchronous. Matching retained rows are deleted in batches, aggregate state is invalidated where required, and a tenant-keyed tombstone suppresses delayed events at or before the cutoff for the seven-day lateness window. Environment delivery keys cannot request or inspect erasure.

​
Raw telemetry export

/api/v1/telemetry/exports is a management-only signed-webhook sink. A cli_ token or app-scoped admin_ key can create/list destinations, inspect or CAS-update one, rotate its shown-once signing secret, request a retained 30-day backfill, inspect bounded delivery diagnostics, and retry an eligible delivery. Destinations must use HTTPS port 443 and an exact host allowed by the account’s export policy. Delivery is at least once. Data already delivered to a customer destination cannot be recalled by Superflag erasure, so that destination must enforce its own retention and subject-erasure policy.