Create or update a fragment
Creates the fragment with this reference on the site (201, active unless status says otherwise), or updates it (200). The reference is the address: it never changes here. Sending the same body again leaves the same state and answers 200.
The body describes the whole fragment. On an update, a field left out is reset: lang to fr, description to none, key_values to {}. Only status keeps its current value when absent.
Pausing a fragment keeps the site default and the rules that point to it: their pages answer 204. warnings lists them. There is no DELETE: deleting a fragment is a console action; pause it instead.
The body is checked before the site is looked up: an invalid body on an unknown site is a 422, not a 404.
Authorizations
A management token: ds_mgmt_ followed by 40 lowercase hexadecimal characters, created by an owner in Settings → Management tokens. Opaque: send it as is, in the Authorization header only.
Path Parameters
The site's bare domain, normalized like the console form (trimmed, lowercase). www.news-site.example and news-site.example are two different sites. A domain that is not a site of this organisation — absent, another organisation's, or not a valid domain — is 404, except on PUT /v1/sites/{domain}, which creates the site and answers 422 for an invalid domain.
The fragment reference, sent as one path segment: encode the whole reference once with encodeURIComponent, so every / travels as %2F (/1234567/news-site/organic/politics → %2F1234567%2Fnews-site%2Forganic%2Fpolitics). Unencoded slashes match no operation (404); a double-encoded reference (%252F…) is refused (422). A reference is case-sensitive: 1 to 200 characters among A-Z a-z 0-9 / _ - . :, and no path segment may be . or .. on its own (URL processing would remove it). The value below is the decoded reference.
^[A-Za-z0-9/_.:-]{1,200}$Body
Send Content-Type: application/json and a JSON object of at most 262,144 bytes.
The fragment, as a whole: on an update, lang, description and key_values are reset to their default when absent. Only status keeps its current value when absent.
Required. Trimmed, and must not be blank once trimmed.
1Exact value, not trimmed. Absent: active on creation, unchanged on update.
active, paused Exact value, not trimmed. Absent: fr, on an update too — send it every time.
fr, en, de, es, it Trimmed. Absent, empty or blank: no description (null).
Legacy targeting key-values, {"key": ["value", …]}; {} when none. Keys match ^[a-z0-9_-]+$ exactly (not trimmed; __proto__ is refused). Each key has a non-empty list of strings; each value is trimmed, and must then be non-empty and without commas or line breaks.
Response
The fragment existed and was updated (or left unchanged).
A Fragment, plus what a paused fragment still serves.
Stable fragment id (frg_…). Never changes.
The site id (sit_…).
The site domain.
The fragment reference. Null for a fragment created in the console without one: it is listed, but this API cannot write it, target it with a rule, or make a card eligible on it.
The fragment name.
The description, or null.
The fragment language: fr, en, de, es or it.
Legacy targeting key-values, {"key": ["value", …]}; {} when none. Keys match ^[a-z0-9_-]+$ exactly (not trimmed; __proto__ is refused). Each key has a non-empty list of strings; each value is trimmed, and must then be non-empty and without commas or line breaks.
paused: every page that resolves to this fragment answers 204 on the fragment endpoint.
active, paused Creation time, UTC.
For a paused fragment, what still resolves to it and therefore answers 204: "site default", "target of N rules" ("target of 1 rule"). [] for an active fragment, or a paused one nothing resolves to.