API changelog

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.

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, and the version in effect is echoed back on every response. Each entry below is a date you can pin. A request without the header uses the latest version; an unknown date is a 400. Pin it in production so an additive default never shifts a payload under you.

While the API is in developer preview, every response also carries X-Forge-Stability: preview — the whole surface shares one stability level; there are no per-endpoint stability labels.

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-07-05 — TypeScript SDK & Terraform provider

Two more first-party clients ship off the shared OpenAPI spec, both drift-gated against it like the Go SDK:

• The TypeScript SDK — @managed/forge (npm install @managed/forge), a zero-dependency client for Node 18+ over the global fetch. Envelope-aware, with auto-pagination, an automatic Idempotency-Key on POSTs, retries honoring Retry-After, job helpers (jobs.waitSuccess), typed ForgeErrors, and webhook verification. Ships ESM + CJS with bundled types.
• The Terraform provider (managed-dev/forge) — declare your fleet as code with forge_site, forge_environment, forge_domain, forge_api_key, and forge_team resources plus a forge_site data source. A thin adapter over the Go SDK; works with Terraform and OpenTofu. Install today via a dev override — Registry publication is next.

2026-07-04 — PHP 8.2–8.5 and per-site version switching

The PHP matrix moves to 8.2 / 8.3 / 8.4 / 8.5 (default 8.3); end-of-life 8.1 is dropped. With it ships a first-class way to move a site between versions:

• POST /v1/sites/{id}/php-version (sites:write) switches a site and its environments to a target version as a 202 job.
• A composer.lock guardrail on bedrock sites rejects a switch the lockfile’s PHP constraint can’t satisfy (400); dry_run previews the change and force overrides the guard. Not applicable to static/wasm sites.
• Available as mf sites php-version, Sites.SwitchPHPVersion in the Go SDK, and the switch_site_php MCP tool.

2026-07-04 — account rollups, calendar windows & richer audit

Fleet-level answers without per-site loops, and a tighter access-governance story:

• New rollups: GET /v1/security/summary, GET /v1/backups/status, GET /v1/usage/storage, and GET /v1/teams/{id}/insights/summary (team Core Web Vitals).
• Insights accept from/to calendar windows (RFC3339) alongside rolling days, so reports are reproducible.
• API keys take an optional expires_at; audit feeds on account, team, and site gain event/actor/since/until filters; site and team lifecycle events (site.created, site.deleted, site.transferred, team.member_added, team.invite_created) join the catalog; job results now carry the ids of what they produced.

2026-07-02 — in-app notifications & the event catalog

The event spine grows a delivery layer beyond webhooks:

• GET /v1/notifications (with unread/bell/category/severity filters), GET /v1/notifications/unread-count, and POST /v1/notifications/read.
• GET/PUT /v1/notification-preferences — per-category email preferences.
• Every event type now carries a severity plus in-app and email flags, and GET /v1/webhook-endpoints/event-types serves the machine-readable catalog webhook subscriptions are built from.

2026-06-28 — functions: wasm compute

A new resource and a new runtime. Single-file functions build to WebAssembly and serve from an isolated tier under /_fn/<slug> on a site:

• GET/POST /v1/functions, GET /v1/sites/{id}/functions, GET/DELETE /v1/functions/{id}, and 202 build / deploy / rollback jobs, behind the new functions:read/functions:write scopes.
• The wasm runtime joins the capability catalog; cron bindings are rejected for customer functions (untrusted tier).

2026-06-26 — signed webhooks & the events feed

Push instead of poll:

• /v1/webhook-endpoints CRUD with reveal-once whsec_ secrets and a roll endpoint; HTTPS-only targets.
• Deliveries are signed (Forge-Signature) and deduplicated by a stable Forge-Delivery-Id; the delivery log supports replay.
• GET /v1/events (events:read) exposes the same events as a queryable feed for backfill and reconciliation.

2026-06-26 — the /v1 surface ships end-to-end

The full customer surface — 149 operations — is live and drift-gated against one OpenAPI spec, with the first-party tooling generated from it:

• The Go SDK (terriblegit.com/terrible/forge-go) covering every operation, with auto-idempotency, retries, pagination iterators, and job helpers.
• The mf CLI (go install terriblegit.com/terrible/mf/cmd/mf@latest) with --json machine output and --wait/--follow on async commands.
• The MCP server (mf mcp) exposing a scope-inheriting, read-mostly tool set for agents. See the ecosystem overview.

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 — resource:action, with write implying read and the dangerous scopes isolated from every wildcard.
• 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.

Note

Surfaces from this design ship in phases and are recorded as dated entries above as they land. Still on the roadmap: the PHP and Python SDKs, OAuth apps, and multi-runtime (Drupal/Node) support.

next steps

VersioningThe full versioning model and the Forge-Version header.

API ecosystemThe SDK, CLI, and MCP server — generated from one spec.

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