> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Export and import with Postman ## Overview Postman can build a collection of every Ada API request, including the [Snapshot API](/reference/snapshot-api/overview), from an AI Agent's own API specification. Set up one collection per Agent, test it with any request, then run the export, validate, and apply requests from the `config` folder. Read the [prerequisites](/reference/snapshot-api/getting-started#prerequisites) before the first import. Postman does not change what the API requires of the target Agent. ## Limitations * **One collection per Agent.** Each Agent has its own API key and host. The export runs from one collection and the import from another. Duplicating the first collection is the quickest way to make the second. * **Two requests are not in the specification.** The archive download and the archive upload go to temporary links, not to the API. You add those two requests yourself, with **No Auth**. The steps below show how. * **Download the archive with Send and Download.** A plain **Send** shows the archive as response text and does not save it. Name the saved file with a `.tar.gz` extension. * **Postman on the web cannot send files.** Use the Postman desktop app, or install the Postman Desktop Agent. * **The collection is a copy of the specification.** When the API changes, import the specification again. ## Quick start Set up, test, then run. Details for each step are in [Implementation & usage](#implementation--usage). #### Import the source Agent's specification In Postman, click **Import** and paste `https://.ada.support/api/v2/spec`, using the host you use to open the Agent's dashboard. Rename the collection after the Agent. #### Set the key and the base URL On the collection, set **Authorization** to **Bearer Token** and paste the Agent's API key. On **Variables**, set `baseUrl` to the Agent's host plus `/api`. #### Test with any request Open any request, keep **Inherit auth from parent**, and send it. A `200` means the collection is set up. #### Duplicate for the target Agent Duplicate the collection, rename it, and repeat step 2 with the target Agent's key and host. #### Export, validate, apply From the `config` folder, export on the source collection, then validate and apply on the target collection. Add the download and upload requests as described below. ## Implementation & usage Each step, with the Postman controls to use and what to look for in the response. ### Prerequisites * The Postman desktop app, or Postman on the web with the Desktop Agent installed. * Everything in the [prerequisites](/reference/snapshot-api/getting-started#prerequisites): an API key for each Agent, and the target Agent set up by hand. ### Set up a collection for an Agent Every Agent serves its own API documentation at `https://.ada.support/api/v2/docs` and its specification at `https://.ada.support/api/v2/spec`. Use the host you use to open that Agent's dashboard. **To set up a collection:** 1. In Postman, click **Import**, paste the specification URL, and press **Enter**. Postman creates a collection named **Ada API V2** with one folder per API family. The Snapshot API requests are in the `config` folder. 2. Rename the collection after the Agent, for example **Ada API V2 - Sandbox**. 3. Open the collection and click the **Authorization** tab. Set **Auth Type** to **Bearer Token** and paste the Agent's API key from **Config > PLATFORM > API keys**. When Postman offers to secure the key in its Vault, accept. The key then never appears in the collection. 4. Click the **Variables** tab. Set the **Current value** of `baseUrl` to the Agent's host plus `/api`, for example `https://EXAMPLE.ada.support/api`. 5. Click **Save**. Each generated request has its own **Authorization** set to **Bearer Token** with an empty `bearerToken` variable. Before you send a request, open its **Authorization** tab and choose **Inherit auth from parent**. A `401` means you skipped this step. **To test the setup:** 1. Open any request in the collection, for example **Get a list of channels** under `channels`. 2. On the request's **Authorization** tab, choose **Inherit auth from parent**. 3. Click **Send**. A `200 OK` means the key and the base URL are right. **To set up the second collection:** 1. Right-click the collection and choose **Duplicate**. 2. Rename the copy after the other Agent, for example **Ada API V2 - Production**. 3. Repeat the **Authorization** and **Variables** steps with that Agent's key and host, then test it the same way. Use the source Agent's collection for the export and the target Agent's collection for the validate and apply. ### Export a snapshot **To export the source Agent:** 1. In the source collection, open `config` and send **Export the agent configuration as a downloadable archive** with **Inherit auth from parent**. The response has a `job_id`. 2. Open **Get the status and result of a config export/import job**. On the **Params** tab, set the `job_id` path variable to that id. Send it until `status` is `completed`. Poll every 5 seconds for the first minute, then every 15 seconds. 3. Note the names under `result.secrets`. The target must have those secret values, and you supply them in the import request. 4. Download the archive from `result.url`. Paste the link into a browser that keeps the file as `.tar.gz`. Or hold Cmd (Ctrl on Windows), click the link, and use **Send and Download**. Safari unpacks the file and keeps the name, and the import then rejects it. The download link is valid for one hour. If it has expired, send the job request again for a fresh one. ### Validate a snapshot The example below moves the API tools (the `actions` section) from a sandbox to a production Agent, with the secret values they use. **To validate the archive against the target Agent:** 1. In the target collection, open `config` and open **Import a full configuration snapshot, including knowledge articles**. Set **Authorization** to **Inherit auth from parent**. 2. On the **Body** tab, replace the example with your request: ```json {"mode": "validate", "include": ["actions"]} ``` Leave out `include` to validate the whole snapshot. Do not send `secrets` on a validate: the values are stored on the Agent as soon as the request is accepted. A `client_secret_missing` warning in the result names each secret to supply on the apply. 3. Click **Send**. The response has a `job_id` and an `upload.url`. 4. Hold Cmd (Ctrl on Windows) and click the `upload.url` link in the response. Postman opens it in a new request tab, outside the collection, so it sends no Authorization header. Change the method to **PUT**. On the **Body** tab, select **binary**, click **Select File**, and choose the archive. Click **Send**. A `200` with an empty body means the upload succeeded. Anything else means it did not; send the import request again for a fresh link and retry. 5. Send the job status request with the new `job_id` until `status` is `completed`. Allow up to two minutes in `waiting_for_upload`. 6. Read the result. `selection` shows what came along: with `include: ["actions"]`, a variable the API tools use is pulled in too (`"included": ["actions", "variables"]`, `"pulled": {"variables": 1}`). `changes` names what the apply would create, update, and delete. If `result.status` is `blocked`, fix each blocking issue on the target (see [Pre-import checks](/reference/snapshot-api/overview#pre-import-checks)) and repeat from step 3. ### Apply a snapshot **To apply the archive to the target Agent:** 1. Open the import request again. On the **Body** tab, change `mode` to `apply`, keep the same `include`, and add the secret values under the names from the export: ```json {"mode": "apply", "include": ["actions"], "secrets": {"auth_token": "the-value"}} ``` 2. Click **Send**. The response has a new `job_id` and a new `upload.url`. The link from the validate round cannot be reused. 3. Hold Cmd (Ctrl on Windows), click the new `upload.url`, change the method to **PUT**, select the same file under **Body > binary**, and send it. Expect `200`. 4. Send the job status request until `status` is `completed` or `failed`. On `failed`, read `failure_reason` and `failure_detail`; see [When a job fails](/reference/snapshot-api/getting-started#when-a-job-fails) for what to do. 5. Check the target in the dashboard. In the example, the target's **Tools** page now lists only the API tools from the archive, because the `actions` section was replaced. The pulled-in variable exists under **Settings > Variables**, and the secret value you supplied is under **Authentication**. 6. Work through [After the apply](/reference/snapshot-api/getting-started#after-the-apply). ## Best practices * Keep the API key in Postman's Vault, never in the collection's **Initial value**, so it stays out of anything you share or export. * Keep one saved archive per export, named with the date, outside Postman. * Run the validate round every time, with the same `include` as the apply, even for a same-Agent restore. * Name the two collections after their Agents, so the export and the import never run against the wrong one. ## Related features * [Snapshot API overview](/reference/snapshot-api/overview): what a snapshot carries, the pre-import checks, and the limits. * [Getting started](/reference/snapshot-api/getting-started): the prerequisites checklist and the step-by-step procedure. * [Export and import with an AI assistant](/reference/snapshot-api/export-and-import-with-an-ai-assistant): the same flow driven by a prompt. * [Authentication](/reference/introduction/authentication): generate an API key.