Snapshot API

Export and import with an AI assistant

Overview

An AI assistant that can run shell commands, such as Claude Code, can drive the whole Snapshot API flow from one prompt. It exports the source AI Agent, validates against the target, and explains every blocking issue and warning in plain language. It applies only after you confirm. The prompt below carries everything the assistant needs, so you can paste it as-is.

Read the prerequisites before the first import. The assistant works only through the API and cannot connect integrations, enable features, or generate API keys for you.

Limitations

  • The assistant needs a way to run HTTP requests and save files. A chat-only assistant can explain the flow but cannot run it.
  • Never paste API keys or secret values into a shared or logged chat. Give them to the assistant through environment variables.
  • Treat the assistant’s summary as a report, not as proof. Check the target Agent in the dashboard after the apply. Read the job’s warnings yourself.
  • The assistant cannot see the dashboard. Every fix the pre-import checks ask for is a dashboard step you do.

Quick start

Copy the prompt, answer its questions, and confirm before the apply. Details are in Implementation & usage.

1

Prepare the keys

Put the source and target API keys in environment variables or a local file the assistant can read.

2

Paste the prompt

Copy the prompt from Copy the prompt into a new session and send it.

3

Answer the questions

The assistant asks for the two Agent hosts, where the keys are, a working folder, whether the target has content, and which sections to import.

4

Confirm at the gate

The assistant stops before the apply and shows you every deletion by name. Nothing is written until you type apply.

Implementation & usage

How the prompt is built, what the assistant does at each step, and how to give it secrets safely.

Prerequisites

  • An AI assistant with a shell tool, such as Claude Code, and curl on the machine it runs on.
  • The prerequisites completed on the target Agent.
  • The source and target API keys stored where the assistant can read them, for example in environment variables named ADA_SOURCE_KEY and ADA_TARGET_KEY.

Copy the prompt

Paste the block below into a new session. It embeds the endpoint reference and the confirmation step.

You are helping me move an Ada AI Agent's configuration with the Snapshot API. Work only through the API described here. Never print, echo, or write to a file any API key or secret value; refer to them only through the environment variables I name. Do not edit the archive.
INPUTS TO COLLECT BEFORE DOING ANYTHING
Ask me for, and wait for:
1. The source Agent's API base URL, in the form https://<handle>.ada.support/api (or the regional host I use to open its dashboard, plus /api).
2. The target Agent's API base URL. It may be the same as the source for a restore.
3. The names of the environment variables holding the source and target API keys.
4. A local working folder for the archive.
5. Whether the target Agent already has configuration on it.
6. Which sections to import. Offer the list: persona, variables, actions (API tools), handoffs, processes, greetings, languages, playbooks, coaching, custom_instructions, glossary, knowledge, csat_settings, custom_redactions, integrations, web_chat. Recommend the smallest set that does the job. Only if I say "everything" do you import the whole snapshot.
THE API
- Start an export: GET {base}/v2/config/ with header "Authorization: Bearer $KEY". Returns 202 {job_id, status}.
- Start an import: PUT {base}/v2/config/ with headers "Authorization: Bearer $KEY" and "Content-Type: application/json", body {"mode": "validate"|"apply", "secrets": {name: value}, "include": [sections]}. Omit include only for a whole-snapshot import. Send secrets only with mode apply: the API stores the values as soon as it receives the request. mode defaults to validate when omitted, so a missing mode never writes; send it explicitly anyway. Never send allow_bulk_delete (the request is rejected) or allow_unsafe_import (it leaves the Agent with broken links). Returns 202 {job_id, status: "waiting_for_upload", upload: {url, method: "PUT", expires_at}}.
- Upload the archive: PUT the raw .tar.gz bytes to upload.url with curl -sS -f -X PUT -T <file> "<url>". No Authorization header. Expect 200. Ada cannot see this request, so check the exit code yourself.
- Check a job: GET {base}/v2/config/jobs/{job_id} with the same Authorization header. Poll every 5 s for the first minute, then every 15 s. Stop at status completed or failed. Only status means done; progress reaches 100 early.
- Statuses: waiting_for_upload, queued, in_progress, completed, failed.
- An export's result has url (download link, valid one hour, re-issued on every poll), expires_at, and secrets (names of secret values the target must have).
- A validate's result has status (valid|blocked), blockers, warnings, articles.found, selection, and changes. changes has, per section, create/update/delete counts plus created/updated/deleted name lists (up to 50 each; a *_truncated flag means more than shown). selection is null for a whole-snapshot import; otherwise it has requested, included, pulled, and unresolved (references the import could not follow).
- An apply's result has articles {upserted, deleted}, indexing, selection, post_apply_blockers (empty is healthy), and the job has warnings.
- Each blocker or warning has code, entity, parameter, message, reference. Report them in plain language and say what dashboard step fixes each one.
- Sections I list are replaced: items the archive does not carry are deleted from them. Sections pulled in as dependencies are only added to. Sections neither listed nor reached are untouched.
- Errors: 400 means the request body is wrong, for example a misspelled section name; fix it and resend, no upload is lost. 409 means an import is already running; poll it to completion first.
- Failed jobs: failure_reason is a code and failure_detail is the sentence to show me. preflight_failed means blocking issues; nothing was written except that integrations the snapshot lists may have been switched on; re-running changes nothing until the issues are fixed. superseded means a later request replaced this job; poll the newer id. timeout, stalled, and incomplete_knowledge are safe to re-submit with the same archive; the import resumes. partially_applied means part of the snapshot was written; do not retry on your own, explain the state and ask me. For any other code, show me failure_detail and stop.
PROCEDURE
Step 1. If the target has configuration on it, export the target first as the restore point: start the export, poll, download the archive with curl -sS -f -o <folder>/target-restore-point-<date>.tar.gz "<url>". Tell me the file path. This is the only way back.
Step 2. Export the source the same way to <folder>/source-<date>.tar.gz. Report result.secrets: these are the secret values the target must have.
Step 3. Validate on the target: start an import with mode validate and the include list I chose, upload the source archive, poll. Report result.status, every blocker with its fix, every warning, selection (what came along, and anything unresolved), and the changes table with names. Report changes["knowledge.articles"]["delete"] on its own line whenever knowledge is in the result; if it is not zero, state plainly that the apply will delete that many articles from the target and that only my own export of the target can bring them back. Every non-zero delete count is a real deletion.
Step 4. GATE. Stop. If there are blockers, list the dashboard fixes and wait for me to say the fixes are done, then repeat Step 3. If the result is valid, ask me for the values of the secrets named in Step 2 (as environment variable names, never values in chat), and ask me to type the word apply. Do nothing until I do.
Step 5. Apply: start an import with mode apply, the same include list, and the secrets; upload the same source archive to the NEW upload link; poll until completed or failed.
Step 6. Report the final result: articles upserted and deleted, indexing, selection, post_apply_blockers, and warnings. Remind me that search results catch up after the import, that the Audit log shows a "Config Apply" row, to add conversation start events to imported Playbooks, to re-select customer login tokens in API tools that use them, and to run test conversations before going live. Remind me where the restore-point archive is.
Begin by asking for the inputs.

Run the flow

To run the export, validate, and apply flow:

  1. Send the prompt, then answer its six questions.
  2. Let the assistant export the target (if it has content) and the source. Note where it saved both archives.
  3. Read its validate report. For each blocking issue, do the dashboard step it names, then tell the assistant to validate again.
  4. When the result is valid, read the delete counts and selection.unresolved, give it the secret variable names it asks for, and type apply.
  5. Read its final report, then work through After the apply.

Provide secret values safely

The assistant reads keys and secret values from environment variables you name, and uses them only inside request headers and bodies. Before you start, set them in the shell the assistant runs in, for example:

$export ADA_SOURCE_KEY="…"
$export ADA_TARGET_KEY="…"
$export CRM_API_TOKEN="…"

Then give the assistant the variable names, never the values.

Best practices

  • Run the flow first against an Agent that is not live.
  • Import the smallest set of sections that does the job. Say “everything” only when you mean to replace the whole Agent.
  • Keep the restore-point archive the assistant saved until you have tested the target.
  • Read the validate report yourself, in particular the delete counts and names, before you type apply.