Authentifizierung
Senden Sie einen API-Schlüssel als Bearer-Token. Der Schlüssel muss über die Berechtigung sites.view verfügen; ein Schlüssel ohne diese wird mit 403 statt 404 abgelehnt.
Dieser Endpunkt erfordert keine Organisations-ID. Ihr Schlüssel identifiziert bereits die zugehörige Organisation, und die Antwort ist entsprechend eingeschränkt.
Ausprobieren
Ersetzen Sie alles in spitzen Klammern durch Ihre eigenen Werte und den Platzhalter für den Schlüssel durch einen Schlüssel aus Ihrem Dashboard.
curl -X POST https://api.zinndigital.com/v1/bulk-jobs \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "operation": <BulkOperation>, "selector": <BulkSelector> }'Angemeldet? Die API-Konsole in Ihrem Dashboard trägt automatisch Ihre echte Organisations-ID sowie Ihren eigenen Schlüssel ein und führt die Anfrage gegen die Live-API aus, sodass Sie die tatsächliche Antwort sehen können. Öffnen Sie diesen Endpunkt in der API-Konsole
Details
Freezes the selection into a per-site work-list and starts a durable, idempotent workflow. **The submit is instant and the work is not** — this returns `202` as soon as the rows are written, and nothing a person is watching waits on the job itself. Only **eligible** sites are enrolled; ineligible ones are not written as pre-failed rows, because a report padded with rows that never had a chance makes the failures that matter harder to find. `previewBulkJob` is where you see them. A selection that enrolls **nothing** is a `422`, not a job that completes instantly: "completed, 0 of 0" is indistinguishable from success on every screen that renders it. ⛔ A typed `confirm` phrase is required when the selector is wider than an explicit list (`product_line`, `org`) **or** the operation is weighty (`plugin_remove`, `plugin_deactivate`, `blueprint_apply`) at any size. `previewBulkJob` returns the exact phrase in `confirmation_phrase`. ⛔ All the selected sites must belong to **one** organization. A mixed selection is a `422` naming the problem rather than a job whose owner is a guess. Requires `sites.view` plus the operation's own key (see the tag description).
Parameter
| Name | Typ | Erforderlich | Was es ist |
|---|---|---|---|
Idempotency-Key (header) | string | Nein | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Anfragekörper
| Name | Typ | Erforderlich | Was es ist |
|---|---|---|---|
operation | BulkOperation | Ja | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
selector | BulkSelector | Ja | Which sites a job targets. ⛔ There is no `all`. A job belongs to exactly one organization and `all` would span every tenant on the platform; the fleet-wide act is a staff operat… |
selector_value | string | Nein | The selector's argument — a product-line code for `product_line`, an organization id for `org`, a site-group id for `group`. Ignored for `sites`, whose members are `site_ids`. |
site_ids | Uuid[] | Nein | The explicit selection, for `selector: sites`. Every id is fenced to the organizations you can reach, so one belonging to somebody else resolves to nothing rather than to a cros… |
params | BulkJobParams | Nein | The operation's arguments. Which keys are read depends on `operation`: `plugin_install` takes `slugs` + `activate`; `plugin_activate`, `plugin_deactivate` and `plugin_remove` ta… |
confirm | string | Nein | The typed confirmation phrase, required when `previewBulkJob` answers `confirmation_required: true`. Send exactly the value it returned in `confirmation_phrase`. ⛔ Whether it is… |
note | string | Nein | Free text kept with the job, for whoever reads the report later. |
Antwort
| Name | Typ | Erforderlich | Was es ist |
|---|---|---|---|
id | Uuid | Ja | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | Ja | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
operation | BulkOperation | Ja | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
params | BulkJobParams | Ja | The operation's arguments. Which keys are read depends on `operation`: `plugin_install` takes `slugs` + `activate`; `plugin_activate`, `plugin_deactivate` and `plugin_remove` ta… |
selector | BulkSelector | Ja | Which sites a job targets. ⛔ There is no `all`. A job belongs to exactly one organization and `all` would span every tenant on the platform; the fleet-wide act is a staff operat… |
selector_value | string | Ja | — |
status | BulkJobStatus | Ja | ⛔ `partial` is a real outcome, not a rounding of the other two. A job where 4 of 900 sites failed is neither a success nor a failure, and reporting it as either is how a bulk ac… |
requested_by | string | Ja | Who asked for it. |
note | string | Ja | — |
created_at | string | Ja | — |
updated_at | string | Ja | — |
settled_at | object | Ja | When the job finished; `null` while it is still running. |
counts | BulkJobCounts | Ja | — |
progress | BulkJobProgress | Ja | How far along a job is, how fast it is going and how much longer it has. ⛔⛔ **Every estimate here is nullable, and a `null` must never be rendered as `0`.** `rate_per_minute: 0`… |
Fehler, die dieser Endpunkt zurückgeben kann
401 · 403 · 409 · 422 · 429