Skip to main content
The management API lets a script write sites, fragments, the site default, routing rules, card eligibility and API keys. It applies the console’s rules, described on sites and fragments, cards and how delivery works, and never serves a card. Each operation has a page under Endpoints, generated from openapi-management.json.

​
Authentication and tokens

Every call sends a management token in the Authorization header:
  • An owner creates it in Settings → Management tokens; it is shown once. It acts on the whole organisation, with no finer rights, and an owner’s token does not expire.
  • Revoke it there once the script is done, or at once if it may have leaked: the next call is a 401.
  • A management token (ds_mgmt_…) is not an API key (ds_live_…): each API refuses the other’s (keys and tokens).
  • api.shftd2.com only (app.shftd2.com answers 404); cookies are never read.
Keep the token out of your shell history and files, and check first which organisation it writes to:
account.id is also your partner_id on the delivery API.

​
Limits and errors

Writes send Content-Type: application/json and a JSON object ({} for a DELETE) of at most 262,144 bytes; unknown fields are refused, nested ones included. Responses are JSON, Cache-Control: private, no-store; lists are {"items": [...]}, without pagination. Errors are {"error": {"code", "message", "field"?}}: branch on code and field, message is for people. Nothing is written until every check passes, in this order: token and limits, body (400, 422), the object in the path (404), stored state (403, 409, 422).
  • Per token: 120 requests per minute, of which at most 60 writes (PUT, POST, DELETE).
  • Per IP: 30 failed authentications and 600 requests with a well-formed token per minute.
  • RateLimit-Policy: "token";q=120;w=60, "write";q=60;w=60 on every response; nothing gives the calls left.
  • Counters are per Cloudflare location, so approximate: one write per second stays well within.

​
References

A fragment’s address is its site’s domain plus its reference, e.g. /1234567/news-site/organic/politics.
  • {domain} is the bare, lowercase domain; www.news-site.example and news-site.example are two sites.
  • A reference is case-sensitive: 1 to 200 characters among A-Z a-z 0-9 / _ - . :, no segment . or ...
  • In a path, encode it once with encodeURIComponent, slashes included: double-encoded (%252F…) is a 422, unencoded slashes a 404.
  • In a JSON body (ref, default_fragment_ref, routes[].ref, fragments[].ref), send it plain.
  • A fragment listed with "ref": null is out of the API’s reach until you give it a reference in the console. A reference never changes through the API: it is the address.

​
Writes and idempotency

  • PUT on a site or a fragment creates or updates it (201, then 200): a script can run twice.
  • PUT …/routes gives every rule a new id; a second DELETE of a rule is a 404.
  • Clearing the default and revoking a key are repeatable (200, same state).
  • POST …/routes answers 409 if the rule exists; POST /v1/keys creates a key on every call.
Two PUTs replace a whole list. PUT …/routes replaces every rule of the site: {"routes": []} deletes them all. PUT …/eligibility replaces the card’s list in your organisation: {"fragments": []} makes your active card eligible everywhere. Read the current list first. Each list is checked, then applied at once; on any error nothing changes, and overlapping calls keep the last write.

​
Sites and fragments

PUT /v1/sites/{domain} registers or updates a site: name absent keeps it, "" clears it; default_fragment_ref names an active fragment, so not in the creating call; domain in the body is refused. PUT /v1/sites/{domain}/fragments/{ref} writes the whole fragment: name (required), lang, description, status (absent: active on creation, unchanged on update); see sites and fragments. key_values is accepted for existing integrations, outside the documented contract.
On a fragment update, a field you leave out is reset, not kept: lang goes back to fr; description and key_values are cleared. Only status is kept.
Pausing the site default or a rule’s target says so in warnings, e.g. ["site default", "target of 2 rules"].

​
Defaults and routing rules

How rules and the default resolve a page: resolution.
  • PUT /v1/sites/{domain}/default-fragment with {"ref": …} sets an active fragment of the site; DELETE with {} clears it and keeps the fragment.
  • PUT …/routes with {"routes": [{"path_prefix", "match", "ref"}]} replaces the rules; POST …/routes adds one (422 once the site has 200); DELETE …/routes/{id} removes one.
  • Paths come back in their stored, canonical form.

​
Cards and eligibility

GET /v1/cards lists your cards and the platform cards ("account_id": null), in every status. GET and PUT /v1/cards/{id}/eligibility read and replace a card’s fragments, named by domain and reference, your organisation’s only. What eligibility means: cards. A platform card’s list can be read, not written (403), and an empty one is not conclusive: other organisations’ choices are never shown.

​
Delivery keys

  • POST /v1/keys with an optional {"name"} answers 201 with the full key in key. The key is in that response only: store it at once, out of logs and tickets; only its prefix is listed after.
  • If that response is lost, do not retry: list the keys, revoke the one you never received, create another.
  • GET /v1/keys lists every key, revoked ones included. DELETE /v1/keys/{id} with {} revokes one.

​
Prepare a client

A script that seeds or syncs an organisation:
  1. Reads the token from its environment, never an argument or a file, and never prints it.
  2. Calls GET /v1/me first and stops unless account.id is the intended organisation.
  3. Writes only what differs from what it read (paths and domains in stored form).
  4. Writes site by site: site, fragments, default, rules. Eligibility comes last, one complete list per card, and not at all if an earlier step failed.
  5. Spaces its writes and waits for Retry-After on a 429.
  6. Creates an API key only when needed, in its own step, and keeps the secret.
  7. Changes nothing on a second run.
  8. Ends with the token revoked in Settings → Management tokens.

​
Console-only actions

  • Creating, editing, activating, archiving or deleting a card.
  • Deleting a site or a fragment; through the API, pause the fragment instead.
  • Deleting a revoked API key; managing management tokens (owners only) and members.