Exporting a library

GET /export writes the tag groups and library sets you choose to a file - in exactly the shape POST /import reads a file back from. What this downloads can be imported again, whether into the same organization as a backup before a replacing import, or into a different one entirely.

Permission

BatchProcessingExport

Read-only, unlike import: it depends on the list and read permission of tag groups, tags and variables, and nothing that creates, updates or deletes. See API permissions.

VariableReadSecrets is required only when secretExportOption=Value is asked for - see Secret values below. Every other option is available without it.

Choosing what to export

Parameter
tagGroupId	Repeated. The tag groups to write, by ID.
variableSetId	Repeated. The library sets to write, by ID.
secretExportOption	Value, Hint, Hash or Blank (default). What a sensitive value writes in place of itself.

At least one tagGroupId or variableSetId is required - asking for neither is 400. A requested ID that does not exist in your organization is 404.

GET /export?tagGroupId=1&variableSetId=2&variableSetId=3&secretExportOption=Hint

Credits

An export costs one credit per library set (variableSetId) - the example above costs 2. Tag groups cost nothing. Your organization must have enough credits left for every library set you name: if it does not, the whole request is refused with 429 Too Many Requests before anything is read, rather than writing a partial file.

A library set's parent does not have to be selected for the export to name it: only the parent's slug is written, which an import resolves against whatever is already in the organization or defined in the same file

• see Parent library sets.

Secret values

Option	What a sensitive variable's values become
Value	The actual value, in its own type - a real JSON number for a Number variable, and so on. Requires VariableReadSecrets.
Hint	Each value's hint - its opening characters, or asterisks for a short value - written as a JSON string regardless of the variable's type. See Sensitive values.
Hash	Each value's hash, salted with the organization, written as a JSON string.
Blank	An empty string.

A non-sensitive variable always exports its values' actual data, whatever secretExportOption was asked for - the option only ever governs what a sensitive variable hands over.

Asking for Value without holding VariableReadSecrets is refused outright with 403, rather than silently downgraded to one of the other options - a file that quietly said less than what was asked for would be a worse surprise than a refusal.

Hint, Hash and Blank always write a JSON string, even for a Number variable - there is no numeric hint or hash to write instead. Re-importing such a file into a Number (or Json or Certificate) variable that still expects a value of its own type fails with 400; only Value round-trips a sensitive non-string-shaped variable successfully. Boolean never comes up here, since a Boolean variable can never be sensitive.

The file

200 OK

{
  "tagGroups": {
    "Environment": ["Development", "Production"]
  },
  "librarySets": {
    "orders-service": {
      "slug": "orders-service",
      "description": "Config for the orders service",
      "parent": "common",
      "variables": {
        "DatabaseConnection": {
          "values": [
            { "value": "Server=prod.internal;Database=orders", "scopes": ["Environment: Production"] }
          ]
        },
        "ApiToken": {
          "sensitive": true,
          "values": [
            { "value": "****************", "scopes": [] }
          ]
        }
      }
    }
  }
}

Tag groups, tags, library sets and variables are all written in name order, and a set's values in the order they were created - so re-running the same export produces the same file, worth keeping under version control.

From the management UI

The Batch section's Export subsection picks tag groups and library sets from two typeaheads, offers the same four secret options (with Value disabled unless you hold VariableReadSecrets), and downloads the result directly - no separate request needed. See The management UI.

Practical notes

• Export before you replace. POST /import?replaceExisting=true deletes everything first and cannot be undone - export what you have while it is still there.
• A secret exported as Hint, Hash or Blank cannot be re-imported as the original secret. The value still comes back marked sensitive, but re-importing it stores the hint, hash or empty string itself as a new sensitive value - with a new hint and hash computed from that text, not the original secret. Export as Value if the point is to move secrets somewhere else, not just to record that they exist.