API changelog

Preview This is the running record of changes to the managed.dev API, plus the policy that governs them. Every dated entry corresponds to a Forge-Version you can pin to, and the policy below is the contract for how — and how rarely — your integration can break.

Developer preview

The managed.dev public API is in active development. The API is in developer preview: while endpoints, scopes, and payloads can still change ahead of general availability, those changes are recorded here.

how versioning works

The API uses two version axes, the Stripe model — see versioning:

• URL major (/v1). Only a breaking shape change bumps the URL. Within /v1, new fields and endpoints are added without warning and must be ignored if unknown — additive changes are never breaking.
• Dated Forge-Version header. Behavior is pinned to a date, e.g. Forge-Version: 2026-06-23. Each entry below is a date you can pin. A request without the header uses your account’s default version. Pin it in production so an additive default never shifts a payload under you.

Note

A change that would alter an existing field’s meaning, remove a field, or tighten validation ships only as a new dated version — never silently into an existing one. You upgrade by changing the header and testing, on your schedule, with the deprecation window below.

deprecation policy

When a version is superseded:

• The old version keeps working for its deprecation window — published per change, never shorter than the window stated in the versioning policy.
• Deprecated fields and endpoints are flagged in the OpenAPI spec and surfaced by the SDKs so you see them at build time.
• A Deprecation response header and a sunset date warn live traffic still on the old shape before anything is removed.

Breaking changes are rare by design. The point of the dated-version model is that you adopt them deliberately, not because we shipped on a Tuesday.

changelog

2026-06-23 — Developer preview

Preview The initial public design of the /v1 API. This release establishes the foundations everything else builds on:

• Scoped API keys — mfk_/mfs_ credentials, reveal-once and hashed at rest, with TTLs and optional IP allowlists.
• The scope grammar — product.resource:action, with write implying read and the dangerous scopes isolated from every wildcard and preset.
• The response envelope — data + request_id, cursor pagination, and the typed error envelope.
• Async jobs — 202 Accepted + a job, consumable via the body, SSE, or ETag long-poll.
• Capability discovery — runtime on every site plus GET /v1/sites/{id}/capabilities, so clients stay runtime-agnostic.
• Idempotency, rate limits with X-RateLimit-* headers, and signed webhooks.

Caution

Surfaces marked elsewhere as roadmap — the SDKs, mf CLI, Terraform provider, MCP server, OAuth apps, and multi-runtime (Drupal/Node) support — are part of this design but ship in later phases. Their arrival will be recorded as dated entries here.

next steps

VersioningThe full versioning model, the Forge-Version header, and stability tiers.

API ecosystemThe roadmap surfaces — SDKs, CLI, Terraform, MCP — generated from one spec.

API overviewStart here: the /v1 API, its thesis, and the resource model.