Cache, redirects & secrets

Three small, closely-related resources live here: the cache (purge it, per environment), redirects (read and replace a site’s edge redirect rules), and secrets (dedicated per-environment secret endpoints, still in developer preview). Each is governed by its own scope, so a deploy bot that purges caches never holds the power to rewrite redirects.

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.

Two different scopes of 'where'

Cache purges are per environment — staging and production have separate caches, so the path names the environment. Redirect rules are per site — they apply at the edge, so the path stops at the site.

Cache

POST /v1/sites/{siteID}/environments/{envID}/cache/purge  

cache:write

Purge the environment’s page cache — everything, one URL, or one tag. The body is optional; sending none purges the whole cache. Because a full purge briefly raises origin load, the endpoint returns 202 Accepted with a job you can wait on rather than blocking.

Name	Type	Required	Description
type	string	no	all, url, or tag (default all)
url	string	when type=url	purge exactly this URL
tag	string	when type=tag	purge every entry carrying this cache tag

Redirects

Method + path	Scope	Does
GET /v1/sites/{siteID}/redirects	redirects:read	list the site’s edge redirect rules
PUT /v1/sites/{siteID}/redirects	redirects:write	replace the full rule set and apply it → 202 + a job

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 source path, matched at the edge), a to (a destination path or absolute URL), and a code (301, 302, 307, or 308).

Read, edit, replace

mf sites redirects get site_01J7Q2 --json > redirects.json
# edit redirects.json, then:
mf sites redirects set site_01J7Q2 --json redirects.json

Worked example — purge the cache

Purge one URL on production after a content fix, and wait on the job. Pass an Idempotency-Key so a retry doesn’t queue a second purge.

cURL

Purge one URL

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-pricing-2026-07-04" \
  -H "Content-Type: application/json" \
  -d '{ "type": "url", "url": "https://www.example.com/pricing/" }'

Go

Purge one URL

client := forge.New(os.Getenv("FORGE_TOKEN"))

job, err := client.Environments.PurgeCache(ctx, "site_01J7Q2", "env_01J8D9",
    &forge.PurgeCacheParams{Type: "url", URL: "https://www.example.com/pricing/"})
if err != nil {
    return err
}
if _, err := client.Jobs.WaitSuccess(ctx, job.ID, nil); err != nil {
    return err
}

mf CLI

Purge one URL

mf envs cache-purge env_01J8D9 --url https://www.example.com/pricing/ --wait

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

{
  "data": {
    "id": "job_01J9TT",
    "type": "job.cache_purge",
    "status": "queued",
    "progress": 0,
    "created_at": "2026-07-04T01:20:00.300Z",
    "resource": { "type": "job", "id": "env_01J8D9",
                  "site_id": "site_01J7Q2", "env_id": "env_01J8D9" },
    "links": { "self": "/v1/jobs/job_01J9TT", "stream": "/v1/jobs/job_01J9TT/stream" }
  },
  "request_id": "req_01JAD3"
}

Worked example — replace the redirect set

Add one rule without dropping the rest: read the current set, append, PUT it back.

cURL

Replace the redirect rules

curl -X PUT https://api.managed.dev/v1/sites/site_01J7Q2/redirects \
  -H "Authorization: Bearer mfk_live_9aF2…" \
  -H "Forge-Version: 2026-06-23" \
  -H "Idempotency-Key: redirects-2026-07-04" \
  -H "Content-Type: application/json" \
  -d '{
    "redirects": [
      { "from": "/old-pricing", "to": "/pricing/", "code": 301 },
      { "from": "/summer-sale", "to": "https://shop.example.com/sale/", "code": 302 }
    ]
  }'

Go

Replace the redirect rules

current, err := client.Sites.GetRedirects(ctx, "site_01J7Q2")
if err != nil {
    return err
}
rules := append(current.Redirects,
    forge.Redirect{From: "/summer-sale", To: "https://shop.example.com/sale/", Code: 302})

job, err := client.Sites.PutRedirects(ctx, "site_01J7Q2", rules)

mf CLI

Replace the redirect rules

mf sites redirects set site_01J7Q2 --json redirects.json

The 202 returns a job.redirects_apply job that finishes when the rules are live at the edge.

Secrets Preview

Developer preview

Dedicated secrets endpoints are designed but not yet shipped. The shape below reflects the current design and may change before general availability.

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

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; it takes effect on the environment’s next deploy.

What you can do today: an environment’s configuration — its security, performance, and observability settings — is readable and patchable now via GET/PATCH /v1/sites/{siteID}/config and GET /v1/sites/{siteID}/environments/{envID}/config, which returns the inherited / override / effective merge. See the environments resource and config & secrets.

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 and redirect-apply jobs these endpoints return.