Export and import with Postman

Overview

Postman can build a collection of every Ada API request, including the Snapshot API, 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 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

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: 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://<handle>.ada.support/api/v2/docs and its specification at https://<handle>.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:

   1
   {"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) 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:

   1
   {"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 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.

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: what a snapshot carries, the pre-import checks, and the limits.
• Getting started: the prerequisites checklist and the step-by-step procedure.
• Export and import with an AI assistant: the same flow driven by a prompt.
• Authentication: generate an API key.