Applies a snapshot produced by GET /v2/config/ — the whole configuration document and the Agent's knowledge articles — reading it from an archive you upload rather than from a request body. Use it to restore an Agent, or to clone one Agent's configuration onto another.

Two calls

1. PUT /v2/config/ returns a job_id and an upload block holding a short-lived url.
2. PUT the raw .tar.gz to that url in one request — no form encoding, no Content-Type needed.

Then poll job_id at GET /v2/config/jobs/{job_id}. The job waits in waiting_for_upload until the archive appears and starts on its own.

The bytes never pass through this API, so the archive may be far larger than a request body allows, and a snapshot from an Agent on one region imports onto an Agent on another with no access between them.

mode defaults to validate

An omitted mode is a dry run. Send mode: "apply" to write anything.

validate reads the archive and reports what an apply would do, without writing — including changes["knowledge.articles"]["delete"], the number of articles the full replace would remove. It is the only place the destructive half is enumerated beforehand, so run it before every apply.

Narrowing what is applied

include lists the sections to import; omit it for the whole snapshot.

Anything a listed section references travels with it, whichever section you name. Ask for playbooks, for example, and the articles, variables, actions and handoffs those playbooks use come too; ask for handoffs and the variables their messages interpolate come with them. That leaves every section in one of three states.

Staying with playbooks: the Agent's playbooks are replaced, so any the snapshot does not carry are deleted. Everything they dragged in is only added to, because your selection reached some of those entities, not all.

So a playbook that uses 4 variables brings those 4 over, and the target Agent's existing variables are not affected — no full replace in this case.

The job's result.selection reports what came over and what could not be resolved.

allow_unsafe_import turns that dependency pull off and downgrades pre-flight blockers to warnings. It leaves an Agent with dangling references that nothing repairs later — never use it on one serving traffic. Validate with the same flag first: result.selection.unresolved lists every reference it will break.

Secrets

Secret values never travel in the archive. Supply them in secrets, keyed by variable name; read the key list from the source export's result.secrets (or the identical block in the archive's config.json).

They are provisioned when the import is requested — before the upload, and never persisted on the job — so a request whose upload never lands still leaves the values provisioned.

A secret the snapshot needs that is neither supplied nor already on the target is a warning, not a failure. The import completes and whatever reads that secret fails at runtime until someone sets it.

Uploading

The URL is valid for one hour, measured when the upload starts, so a slow link finishing later is fine.

Check the status your upload returns. Ada never sees that request, so a rejected upload is indistinguishable from one that never ran — the job waits, then fails. curl exits 0 on an HTTP error unless you pass -f. To retry, just PUT /v2/config/ again: a job still waiting for its archive is replaced, not rejected.

An archive that never arrives fails the job about 90 minutes after submission (upload_not_received); one over the size ceiling fails as soon as it lands (upload_too_large). The archive is read only when the job runs — the manifest describing it sits at the end of the file — so a malformed snapshot fails the job seconds after it starts, before anything is written, rather than returning a 400 here.

What an apply does

Each entity applies with the semantics the export documents: full replace matched on the natural key.

Knowledge is full replace: an article the snapshot does not carry is deleted, however many that is. Articles created after the import started are never deleted, and articles with no knowledge source are left alone, since an import cannot recreate one. Leaving knowledge out of include stops every article deletion; articles that your listed sections reference are still added or updated.