Skip to main content

Import Configuration

Endpoint​

/i/import

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Overview​

Imports previously exported configuration data into an application. Reads an uploaded JSON export file, validates all items for compatibility, performs ID mapping, and inserts the configuration into the target application with automatic dependency resolution.

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Required permission: Update on the Config Transfer feature (config_transfer)

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key for authentication
auth_tokenStringYes (or api_key)Auth token for authentication
app_idStringYesTarget application identifier (where to import configuration)
import_fileFileYesMultipart-uploaded JSON file exported from the Config Transfer export endpoint.

import_file Format​

JSON file structure exactly as exported from /o/export:

[
  {
    "name": "feature_name",
    "data": [],
    "dependencies": {}
  }
]

Response​

Success Response​

"Success"

Response Fields​

FieldTypeDescription
(root value)StringStatus message on successful import

Error Responses​

HTTP StatusError ResponseDescription
400{"result": "Missing parameter \"api_key\" or \"auth_token\""}Missing authentication parameters
401{"result": "No app_id provided"}Missing target app identifier
401{"result": "User does not have right"}User lacks Update permission on Config Transfer feature
500{"result": "Error in import"}Import validation or data insertion failed

Behavior/Processing​

Import Process​

  1. Validation Phase:

    • Validates update permission for config_transfer feature
    • Reads and parses uploaded JSON file from import_file
    • Validates imported data structure

  2. Feature Validation:

    • For each feature in import file:
      • Dispatches /import/validate to the feature plugin
      • Receives validation result with status and old→new ID mapping
      • Collects plugin ID maps

  3. Dependency Validation:

    • Processes dependency items:
      • Dispatches /import/validate for each dependency
      • Builds complete ID map (old IDs → newly generated IDs)

  4. ID Reference Updates:

    • Replaces all references in imported data:
      • APP_ID placeholder → Target application ID
      • OWNER_ID placeholder → Importing user's member ID
      • Old object IDs → Newly generated IDs
    • Ensures all cross-references remain valid

  5. Import Execution:

    • Imports dependencies first (in correct order)
    • Then imports main items
    • Dashboard widgets imported last due to dependency on dashboards
    • Dispatches /import event to each feature plugin for data insertion

  6. Data Persistence:

    • Each feature plugin manages writing to its own collections
    • Maintains referential integrity across features

Database Collections​

CollectionUsed forData touched by this endpoint
/importDispatchesevent to feature plugins; Dashboard plugin writes to dashboard collections; Cohorts plugin writes to cohort collections; Segments plugin writes to segment collections; etc.

Examples​

Example 1: Import configuration file to target app​

Request (multipart/form-data):

curl -X POST "https://your-server.com/i/import" \
  -F "api_key=YOUR_API_KEY" \
  -F "app_id=TARGET_APP_ID" \
  -F "import_file=@export_config.json;type=application/json"

Where export_config.json contains the JSON array returned by /o/export.

Response:

"Success"

Example 2: Save export, then import to another app​

Step 1: Export from source app: Save the JSON response from /o/export into a file:

curl -G "https://your-server.com/o/export" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "app_id=SOURCE_APP_ID" \
  --data-urlencode 'exportData=[{"id":"dashboards","name":"Dashboards","children":[{"id":"DASHBOARD_ID","name":"Dashboard"}]}]' \
  > export_config.json

Step 2: Import to target app:

curl -X POST "https://your-server.com/i/import" \
  -F "api_key=YOUR_API_KEY" \
  -F "app_id=TARGET_APP_ID" \
  -F "import_file=@export_config.json;type=application/json"

Response:

"Success"

Limitations​

  • File size: Import file size limited by server upload limits (typically 100MB).
  • File format: Current implementation reads import_file and parses it with JSON.parse; archive formats such as .tar.gz are not accepted by this endpoint.
  • Supported features: Only features that implement /import and /import/validate dispatches can be imported. Check plugin documentation for import support.
  • ID replacement mechanism: IDs are replaced using string replacement of APP_ID and OWNER_ID placeholders. Custom serialization logic in imported data may break if not handled properly.
  • Dependency conflicts: If exported item depends on items not being imported, import may fail with validation error from the feature plugin.
  • User-specific data: Some user-specific data (permissions, favorites, personal settings) may not be exported depending on feature implementation.
  • Ownership: Imported items are assigned to the importing user. Previous ownership is not preserved.
  • Duplicate handling: Importing the same configuration twice creates duplicate items (no upsert/merge logic).

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

Already a Customer? Use support portal if you have any questions

Last Updated​

2026-02-16