REST API Documentation
Butler provides a REST API that allows you to interact with some of its features programmatically.
Remember
The "Try it out" feature of the API documentation below does not work when accessed from butler.ptarmiganlabs.com. This is only expected as this site does not know anything about where your Butler instance is running.
The same feature is however also available from Butler itself, see this page.
API Overview
Butler's REST API is documented using the OpenAPI 3.0 specification and provides endpoints for:
- System Management: Health checks, version information, configuration
- File Operations: Copy, move, delete files, create directories
- Task Management: Start Qlik Sense tasks, scheduling operations
- Key-Value Store: Data storage and retrieval operations
- Messaging: MQTT publishing, Slack notifications
- Monitoring: New Relic integration, app dumping
- Utility Functions: Base encoding conversions, app listings
Interactive API Documentation
Butler is a microservice that provides add-on features to Qlik Sense Enterprise on Windows.
Butler offers both a REST API and things like failed reload notifications etc.
This page contains the API documentation. Full documentation is available at https://butler.ptarmiganlabs.com
External Documentation
Butler family of tools on GitHubServers
Default
Operations
Get an array of all enabled API endpoints.
Get an array of all enabled API endpoints, using the key names from the Butler config file.
Note: Endpoints are enabled/disabled in the Butler main configuration file.
Responses
Enabled API enpooints.
Converts strings from base62 to base16.
Converts strings from base62 to base16.
Parameters
Query Parameters
The base62 encoded string that should be converted to base16
"6DMW88LpSok9Z7P7hUK0wv7bF"Responses
Base conversion successful.
Converts strings from base16 to base62.
Converts strings from base16 to base62.
Parameters
Query Parameters
The base16 encoded string that should be converted to base62
"3199af08bfeeaf5d420f27ed9c01e74370077"Responses
Base conversion successful.
Tests if Butler is alive and responding
Copy file(s) between well defined, approved locations.
Copying of files is only posttible between pre-approved directories.
Defining approved source and destination directories is done in Butler's config file.
If the source directory contains subdirectories, these will be copied too.
Request Body
Responses
File copied.
Move file(s) between well defined, approved locations.
Moving of files is only posttible between pre-approved directories.
Defining approved source and destination directories is done in Butler's config file.
If the source directory contains subdirectories, these will be moved too.
Request Body
Responses
File moved.
Delete file(s) in well defined, approved locations.
It is only possible to delete files in pre-approved directories, or subdirectories thereof.
Defining approved directories is done in Butler's config file.
Request Body
Responses
File deleted.
Creates a directory in designated QVD directory.
Creates a directory anywhere in the file system.
If the directory already exists nothing will happen.
If permissions don't allow a directory to be created, or if the path is invalid, an error will be returned.
Request Body
Responses
Directory created.
List all currently defined namespaces.
Get the value associated with a key, in a specific namespace.
Parameters
Path Parameters
"Sales ETL step 2"Query Parameters
"Last extract timestamp"Responses
Key and it's associated value and metadata returned.
Create a new key-value pair in the specified namespace.
If the specified key already exists it will be overwritten.
If the posted data has a TTL, it will start counting when the post occur.
I.e. if a previouly posted key also had a TTL, it will be replace with the most recent TTL.
Parameters
Path Parameters
Name of namespace.
"Sales ETL step 2"Request Body
Responses
Key successfully set.
Delete a namespace and all key-value pairs in it.
Checks if a key exists in a namespace.
Returns true if the specified key exists, otherwise false.
Parameters
Path Parameters
"Sales ETL step 2"Query Parameters
"Last extract timestamp"Responses
Key exist/no-exist returned, together with the data if the does exist.
Delete a key-value pair in a specific namespace.
Parameters
Path Parameters
Name of namespace.
"Sales ETL step 2"Key to use
"ce68c8ca-b3ff-4371-8285-7c9ce5040e42_parameter_1"Responses
Key-value pair successfully deleted.
Retrieve a list of all keys present in the specified namespace.
Parameters
Path Parameters
Name of namespace whose keys should be returned.
"Sales ETL step 2"Responses
Object containing namespace name + list of allkeys in the namespace.
Publish a message to a MQTT topic.
Post events to New Relic.
This endpoint posts events to the New Relic event API.
Request Body
Responses
Data accepted and sent to New Relic.
Post metrics to New Relic.
This endpoint posts metrics to the New Relic metrics API.
Request Body
Responses
Data accepted and sent to New Relic.
Get all information available for existing schedule(s).
If a schedule ID is specified using a query parameter (and there exists a schedule with that ID), information about that schedule will be returned.
If no schedule ID is specified, all schedules will be returned.
Parameters
Query Parameters
Scheduld ID
"e4b1c455-aa15-4a51-a9cf-c5e4cfc91339"Responses
Schedule successfully retrieved.
Create a new schedule.
Request Body
Responses
Schedule successfully retrieved.
Delete a schedule.
Start a schedule.
Start a schedule, i.e. have the scheduler run the associated reload task according to the schedule's cron settings.
Parameters
Path Parameters
Schedule ID.
"e4b1c455-aa15-4a51-a9cf-c5e4cfc91339"Responses
Schedule successfully started.
An object with all information about the started schedule is returned.
Start all schedules.
Start all schedules, i.e. tell the scheduler to run each schedule and start associated tasks according to each schedule's settings.
Responses
Schedules successfully started.
An array with all information about the started schedules is returned.
Stop a schedule.
Stop a schedule, i.e. tell the scheduler to no longer execute the schedule according to its cron settings.
Parameters
Path Parameters
Schedule ID.
"e4b1c455-aa15-4a51-a9cf-c5e4cfc91339"Responses
Schedule successfully stopped.
An object with all information about the stopped schedule is returned.
Stop all schedules.
Stop all schedules, i.e. tell the scheduler to no longer execute any schedule according to its cron settings.
Responses
Schedules successfully stopped.
An array with all information about the stopped schedules is returned.
Get scheduler status.
Get basic status from the core scheduler.
No schedule metadata beyond ID, cron setting and job state will be returned, but as this comes from the core scheduler it is the authorative truth about what jobs are running (and which ones are not).
Responses
Status for all jobs that exist in the core scheduler.
Do a stand-alone reload of a Qlik Sense app, without using a task.
Parameters
Path Parameters
ID of Qlik Sense app.
"210832b5-6174-4572-bd19-3e61eda675ef"Request Body
Responses
App successfully reloaded.
Dump a Sense app to JSON.
Dump a Sense app to JSON.
Get a list of all apps in Sense environment.
Get a list of all apps in Sense environment.
Start a Qlik Sense task.
An optional array of zero or more objects can be passed in the message body. It is used to pass additional info related to the reload task being started.
Currently supported values in this array are:
- A key-value pair that will be stored in Butler's KV store. If Butler's key-value store is not enabled, any key-value information passed in this parameter will simply be ignored.
Settingttl=0disables the TTL feature, i.e. the KV pair will not expire. - A task identified by its taskId that should be started.
- Tasks identified by tags set on tasks in the QMC.
- Tasks identified by custom properties set in the QMC.
This parameter uses a generic JSON/object format (type + payload).
It's thus possible to add new integrations in future Butler versions.
Parameters
Path Parameters
ID of Qlik Sense task.
Butler will ignore the "magic" task ID of "-" (=dash, hyphen). This ID will not be reported as invalid.
"210832b5-6174-4572-bd19-3e61eda675ef"Query Parameters
If set to true, all specified taskIds must exist. If one or more taskIds does not exist in the Sense server, no tasks will be started.
If set to false, all existing taskIds will be started. Missing/invalid taskIds will be ignored.
In either case, missing/invalid taskIds will be reported in the result set back to the client calling the API.
Note: Tasks started by specifying tags and/or custom properties are not affected by this.
trueRequest Body
Responses
Task successfully started.
Start a Qlik Sense task.
An optional array of zero or more objects can be passed in the message body. It is used to pass additional info related to the reload task being started.
Currently supported values in this array are:
- A key-value pair that will be stored in Butler's KV store. If Butler's key-value store is not enabled, any key-value information passed in this parameter will simply be ignored.
Settingttl=0disables the TTL feature, i.e. the KV pair will not expire. - A task identified by its taskId that should be started.
- Tasks identified by tags set on tasks in the QMC.
- Tasks identified by custom properties set in the QMC.
This parameter uses a generic JSON/object format (type + payload).
It's thus possible to add new integrations in future Butler versions.
Parameters
Path Parameters
ID of Qlik Sense task.
Butler will ignore the "magic" task ID of "-" (=dash, hyphen). This ID will not be reported as invalid.
"210832b5-6174-4572-bd19-3e61eda675ef"Query Parameters
If set to true, all specified taskIds must exist. If one or more taskIds does not exist in the Sense server, no tasks will be started.
If set to false, all existing taskIds will be started. Missing/invalid taskIds will be ignored.
In either case, missing/invalid taskIds will be reported in the result set back to the client calling the API.
Note: Tasks started by specifying tags and/or custom properties are not affected by this.
trueRequest Body
Responses
Task successfully started.
Send message to Slack.
Sends a basic message to Slack.
Request Body
Responses
Message successfully sent to Slack.
Additional Resources
- Download OpenAPI JSON - Raw OpenAPI specification
- Butler Examples - Code examples and use cases
- Configuration Guide - API configuration options
Getting Started with the API
- Enable API endpoints in your Butler configuration file
- Configure authentication if required
- Test connectivity using the
/v4/butlerpingendpoint - Explore endpoints using the interactive documentation above
The Butler API follows REST principles and returns JSON responses. All endpoints are prefixed with /v4/ to indicate the API version.