Cache, redirects & secrets

Preview Three small, closely-related env-scoped resources live here: the cache (purge it, read its config), redirects (list and replace rules), and secrets (per-environment config variables). They share a pattern — all are scoped to a single environment, because a redirect or a secret can differ between staging and production — and each is governed by its own write scope.

Developer preview

The managed.dev public API is in active development. Endpoints, scopes, and payloads described here reflect the current design and may change before general availability.

For the product behavior behind these — how caching works, how redirects are matched, and how config and secrets are inherited across environments — see caching, redirects, and config & secrets. This page is the API reference.

Everything here is env-scoped

All paths below sit under /v1/sites/{siteID}/environments/{envID}. A site-level alias resolves to the production environment as a convenience, but the canonical form names the environment — that’s how a secret can be set on staging without touching production.

Cache

Method + path	Scope	Does
POST …/{envID}/cache/purge	cache:write	purge the cache → 202 + a job
GET …/{envID}/cache	cache:read	read cache configuration and current state

cache:writecache:read

POST …/cache/purge accepts an optional body to scope the purge; an empty body purges everything. Because a global purge briefly raises origin load, it returns a job you can wait on rather than blocking.

Name	Type	Required	Description
type	string	no	page, object, or all (default all)
tags	string[]	no	purge only entries tagged with these
paths	string[]	no	purge only these URL paths

Redirects

Method + path	Scope	Does
GET …/{envID}/redirects	redirects:read	list the environment’s redirect rules
PUT …/{envID}/redirects	redirects:write	replace the full redirect rule set

redirects:writeredirects:read

PUT is a full replacement — send the complete rule set you want, not a delta. Read first, edit the array, write it back. Each rule has a from, a to, and a status (301 or 302).

Secrets

Method + path	Scope	Does
GET …/{envID}/secrets	secrets:read	list secret keys (names + metadata, never values)
PUT …/{envID}/secrets/{key}	secrets:write	set or replace a secret’s value
DELETE …/{envID}/secrets/{key}	secrets:write	remove a secret

secrets:writesecrets:read

Secret values are write-only over the API

GET …/secrets returns the keys, not the values — there’s no read-back of a secret’s plaintext, the same way API keys are reveal-once. To change a value, PUT a new one. Setting a secret takes effect on the next deploy of the environment.

Worked example — purge the cache

Purge everything for a production environment, and wait on the job. Pass an Idempotency-Key so a retry doesn’t queue a second purge.

cURL

Purge the page cache

curl -X POST https://api.managed.dev/v1/sites/site_01J7Q2/environments/env_01J8D9/cache/purge \
  -H "Authorization: Bearer mfk_live_9aF2…" \
  -H "Forge-Version: 2026-06-23" \
  -H "Idempotency-Key: purge-after-release-rel_01JE7" \
  -H "Content-Type: application/json" \
  -d '{ "type": "page" }'

Go

Purge the page cache

body := strings.NewReader(`{ "type": "page" }`)
req, _ := http.NewRequest("POST",
    "https://api.managed.dev/v1/sites/site_01J7Q2/environments/env_01J8D9/cache/purge", body)
req.Header.Set("Authorization", "Bearer mfk_live_9aF2…")
req.Header.Set("Forge-Version", "2026-06-23")
req.Header.Set("Idempotency-Key", "purge-after-release-rel_01JE7")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req) // 202 Accepted

mf CLI

Purge the page cache

mf cache purge --env env_01J8D9 --type page

Response — 202 Accepted (Location: /v1/jobs/job_01J9TT)

{
  "data": {
    "id": "job_01J9TT",
    "type": "cache.purge",
    "status": "queued",
    "created_at": "2026-06-24T01:20:00.300Z",
    "resource": { "type": "environment", "id": "env_01J8D9" }
  },
  "request_id": "req_01JAD3"
}

Worked example — set a secret

Set a config secret on the staging environment. The value is write-only — you won’t read it back.

cURL

Set an environment secret

curl -X PUT https://api.managed.dev/v1/sites/site_01J7Q2/environments/env_01J8D9/secrets/STRIPE_API_KEY \
  -H "Authorization: Bearer mfk_live_9aF2…" \
  -H "Forge-Version: 2026-06-23" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk_test_51N…" }'

TypeScript

Set an environment secret

await fetch(
  "https://api.managed.dev/v1/sites/site_01J7Q2/environments/env_01J8D9/secrets/STRIPE_API_KEY",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer mfk_live_9aF2…",
      "Forge-Version": "2026-06-23",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ value: "sk_test_51N…" }),
  },
);

mf CLI

Set an environment secret

mf secrets set STRIPE_API_KEY --env env_01J8D9

Response — the key, never the value

{
  "data": {
    "key": "STRIPE_API_KEY",
    "env_id": "env_01J8D9",
    "updated_at": "2026-06-24T01:21:30Z",
    "applies_on": "next-deploy"
  },
  "request_id": "req_01JAD9"
}

Next steps

CachingHow the page and object caches work before you purge them.

RedirectsHow redirect rules are matched and ordered.

Config & secretsHow config and secrets are inherited across environments.

Jobs resourceWait on the purge job the cache endpoint returns.