/config

Use /config to

Retrieve, modify, or delete configuration information for V‑Spark entities
- Companies
- Organizations
- Folders
- Analytics applications
Retrieve and modify a more limited set of user account settings.
Retrieve the system's readonly status.

/config POST requests must include entity information as top-level JSON data. Higher-level entity information does not need to be included in JSON POST data when entity names are included as path parameters.

Data written to V‑Spark with /config is additive—that is, if objects in request JSON data exist, they are configured to use the request JSON. Objects that do not exist are created.

Synopsis

GET | POST | DELETE /config?token=$token
GET | POST | DELETE /config/users?token=$token
GET | POST | DELETE /config/orgs?token=$token
GET | POST | DELETE /config/folders?token=$token
GET | POST | DELETE /config/apps?token=$token

GET | POST | DELETE /config/$co_short?token=$token
GET | POST | DELETE /config/$co_short/orgs?token=$token
GET | POST | DELETE /config/$co_short/folders?token=$token
GET | POST | DELETE /config/$co_short/apps?token=$token
GET | POST | DELETE /config/$co_short/users/$user?token=$token

GET | POST | DELETE /config/$co_short/$org_short?token=$token
GET | POST | DELETE /config/$co_short/$org_short/folders?token=$token
GET | POST | DELETE /config/$co_short/$org_short/apps?token=$token
GET | POST | DELETE /config/$co_short/$org_short/$folder?token=$token
GET | POST | DELETE /config/$co_short/$org_short/apps/$app_name?token=$token

GET /config/system/readonly?token=$token

$token: Authorization token with the required read or write permissions for the request.
$co_short: Company short name used to filter the request.
$org_short: Organization short name used to filter the request.
$folder: Folder used to filter the request.
$user: The username of a V‑Spark user account.
$app_name: Name of the application to be queried.

Endpoints

/config endpoints accept requests to retrieve, modify, or delete configurations for organizations, folders, applications, and user accounts, and to retrieve V‑Spark's system configuration.

Note: POSTing a configuration for an entity that does not exist creates a new entity with those attributes.

/config: Returns information about all companies in a V‑Spark installation
/config/orgs: Returns information about all organizations that have been defined under companies in a V‑Spark installation
/config/folders: Returns information about all folders that have been defined under organizations in a V‑Spark installation
/config/apps: Returns information about all applications that have been defined in a V‑Spark installation
/config/users: Use /config/users to retrieve, create, and configure V‑Spark user accounts, to retrieve user account status, to retrieve the authorization method used for login, and to retrieve or configure the permissions that they have in V‑Spark and within each company.

Note: Users are associated with companies. Deleting companies in a V‑Spark installation also deletes any users associated with those companies.
/config/system/readonly: Returns information about whether a V‑Spark installation is or is not running in "read only" mode. You cannot call the /config/system API alone without calling /config/system/readonly API.

Example cURL requests

GET

This example request retrieves the configuration for all of the organizations the token has permission to read.

curl -s http://example.company.com:3000/config/orgs?token=TOKEN

The following example request retrieves the configuration for all of the organizations associated with the company DocTestCo the token has permission to read.

curl -s http://example.company.com:3000/config/DocTestCo/orgs?token=$token

The following example request retrieves the account configuration for the testUser user account. The JSON after the cURL request shows an example JSON user data response

curl -s 'http://example.company.com:3000/config/DocTestCo/users/testUser?token=$token'

 {
    "name": "bscott284@medallia.com",
    "email": "bscott284@medallia.com",
    "company": "MedalliaSSO",
    "auth": {
        "verified": true,
        "disabled": false,
        "method": "standard"
    },
    "permissions": {
        "Medallia": {
            "orgs": {
                "Medallia-Demo": [
                    "read",
                    "write"
                ]
            }
        }
    }
}

POST

The following example request creates or modifies the entity defined in the local file post-config.json.

curl -s -X POST -H "Content-Type:application/json" "http://example.company.com/config?token=TOKEN" --data @post-config.json

The following example request creates or modifies the testUser user account to the configuration defined in the local file user-config.json.

curl -s -H "Content-Type:application/json" -X POST 'http://example.company.com:3000/config/DocTestCo/users/testUser?token=$token' --data @user-config.json

DELETE

Use DELETE with /config to delete company, organization, folder, application, user, and system entities and configurations.

Warning: Entity deletion is permanent and cannot be undone.

The following example request deletes the testUser user account from the Docs-Org organization.

curl -s -X DELETE 'http://example.company.com:3000/config/Docs-Co/Docs-Org/users/testUser?token=$token'

The following example request deletes the Test01 folder and all data below it.

curl -s -X DELETE 'http://example.company.com:3000/config/Docs-Co/Docs-Org/Test01?token=TOKEN'

The following example request deletes the Docs-Org organization and all folders and other data associated with it.

curl -s -X DELETE 'http://example.company.com:3000/config/Docs-Co/Docs-Org?token=TOKEN&multi=true&tree=true'

Use these parameters when deleting multiple entities with /config.

tree: Optional. Include tree=true with DELETE requests to delete non-empty entities like companies or organizations that contain lower-level folders or applications. By default, tree=false and entities containing lower-level entities cannot be deleted.
multi: Required to enable the deletion of multiple entities with a single request.

Python example

Use these sample Python scripts to test /config operations:

api_get_config.py

This example command saves system company configuration to an output file.

python api_get_config.py $host $token /config $http_code $output_file

get_deep_config.py

Uses the root token to retrieve the system's company token list and entity hierarchy.

python get_deep_config.py $host:$port $token

api_post_config.py

The first example command writes top-level company JSON to V‑Spark. The specified company is created or updated to the supplied configuration.

python api_post.config.py $host $token /config 200 $input_file

The next example command writes lower-level organization JSON to V‑Spark. The specified organization is created or updated to the supplied configuration.

python api_post_config.py $host $token /config/orgs 200 $input_file

$host

Hostname or URL for the system running V‑Spark.

$port

Port configured for the host system. Default 3000.

$token

Authorization token with the required read or write permissions for the request.

$http_code

The HTTP code expected to be returned with the response.

$input_file

File path for query input.

$output_file

File path for query output.