Welcome to the StackStorm API Reference documentation! You can use the StackStorm API to integrate StackStorm with 3rd-party systems and custom applications. Example integrations include writing your own self-service user portal, or integrating with other orquestation systems.
This document provides an overview of how to use the API. Use the menu on the left to look up details of specific API endpoints. For more information about how StackStorm works, and how to use it, check out the main StackStorm documentation.
A Quick Note
This API is intended for software developers, and those are who are comfortable working with RESTful APIs, and writing some code. You do not need to use this API to work with StackStorm, or to use and write integration packs for StackStorm.
Usually the API is available at https://$ST2_HOSTNAME/api. The default implementation is to use Nginx as a front-end, passing /api requests through to the st2api service, which by default listens on port 9101. On a reference single-system deployment, all processes run on the same system. If you have a multi-system deployment, the components may be running on multiple systems, and may be load-balanced.
To authenticate against the StackStorm API, either an authentication token or an API key (but not both) should be provided in the HTTP request headers. The headers are named X-Auth-Token and St2-Api-Key respectively. In situation when it is impossble to provide a header to the response, query parameters x-auth-token and st2-api-key could be used instead, but would require you to weight in on security implications.
An authentication token is a time-limited access token, granted once a user authenticates, typically using a username and password. This is suitable for short-term, interactive sessions. API Keys do not expire, and are therefore better suited for use with integrating other applications.
If you are using authentication tokens, you need to first obtain a token using the /auth endpoint, and then use the token for future requests against the /api endpoint. To obain a token:
curl -X POST -u 'yourusername:yourpassword' https://$ST2_HOSTNAME/auth/v1/tokens
You can then use the token like this:
# Token as header
curl -H "X-Auth-Token: 4d76e023841a4a91a9c66aa4541156fe" https://$ST2_HOSTNAME/api/v1/actions
# Token as query parameter
curl "https://$ST2_HOSTNAME/api/v1/actions?x-auth-token=4d76e023841a4a91a9c66aa4541156fe"
API Keys can be generated once, and then used indefinitely. To obtain an API Key, you can use the st2 CLI:
st2 apikey create -k -m '{"used_by": "my integration"}'
Note the use of the option -m flag to provide key metadata. This is good practice, because it helps to identify what the key is used for. This is useful if you need to later revoke or disable keys.
Keys can also be created using the apikeys API.
Using the API key:
# Key as header
curl -H "St2-Api-Key: <API-KEY-VALUE>" https://$ST2_HOSTNAME/api/v1/actions
# Key as query parameter
curl https://$ST2_HOSTNAME/api/v1/actions?st2-api-key=<API-KEY-VALUE>
The StackStorm API supports these HTTP methods:
There is also an implicit support of OPTIONS method that will return a set of CORS-related headers.
Methods HEAD and PATCH are not supported in API v1, but might be considered in future iterations.
The default StackStorm installation creates a self-signed certificate. If you are testing this with curl, you may need to disable certificate validation with curl -k. We strongly recommend you configure valid, signed certificates for StackStorm.
The StackStorm API only supports JSON, not XML. Most POST requests require a well-formatted JSON object body.
These are some examples to show how to use the StackStorm API with cURL. You can use any REST-capable client, library or programming language to access the StackStorm API.
Obtaining an authentication token:
$ curl -X POST -k -u st2admin:'Ch@ngeMe' https://$ST2_HOSTNAME/auth/v1/tokens
{"user": "st2admin", "token": "866218ad67e141e4aaddbbb92964e67e", "expiry": "2017-04-06T01:15:06.602758Z", "id": "58e4451ac4da5f1e040fb859", "metadata": {}}
List rules for the ChatOps pack:
$ curl -k -X GET -H 'X-Auth-Token: b99d3f74a16e471992f2a10935637916' 'https://$ST2_HOSTNAME/api/v1/rules?limit=50&pack=chatops'
[{"description": "Notification rule to send results of action executions to stream for chatops", "tags": [], "type": {"ref": "standard", "parameters": {}}, "enabled": true, "name": "notify", "trigger": {"ref": "core.st2.generic.notifytrigger", "type": "core.st2.generic.notifytrigger", "parameters": {}}, "criteria": {"trigger.route": {"pattern": "hubot", "type": "equals"}}, "action": {"ref": "chatops.post_result", "parameters": {"user": "{{trigger.data.user}}", "execution_id": "{{trigger.execution_id}}", "channel": "{{trigger.data.source_channel}}"}}, "pack": "chatops", "ref": "chatops.notify", "id": "58b7089ac4da5f6aa779b85a", "uid": "rule:chatops:notify"}]
Load a new rule:
$ curl -X POST -H 'content-type: application/json' -H 'X-Auth-Token: b99d3f74a16e471992f2a10935637916' --data-binary '{"description": "Sample rule using an Interval Timer.", "enabled": false, "trigger": {"type": "core.st2.IntervalTimer", "parameters": {"unit": "seconds", "delta": 5}}, "criteria": {}, "action": {"ref": "core.local", "parameters": {"cmd": "echo \"{{trigger.executed_at}}\""}}, "pack": "examples", "name": "sample_rule_with_timer"}' https://$ST2_HOSTNAME/api/v1/rules
{
"description": "Sample rule using an Interval Timer.",
"tags": [],
"type": {
"ref": "standard",
"parameters": {}
},
"enabled": false,
"name": "sample_rule_with_timer",
"trigger": {
"ref": "core.cab3cb5f-f0c5-466b-b27c-dc481fc19fac",
"type": "core.st2.IntervalTimer",
"parameters": {
"unit": "seconds",
"delta": 5
}
},
"criteria": {},
"action": {
"ref": "core.local",
"parameters": {
"cmd": "echo \"{{trigger.executed_at}}\""
}
},
"pack": "examples",
"ref": "examples.sample_rule_with_timer",
"id": "58eddb871878c12be65c9fdd",
"uid": "rule:examples:sample_rule_with_timer"
}
For further examples of using the API, check out the st2 --debug command. If you know which st2 command you want, run st2 --debug <st2 command>, and it will display the equivalent cURL commands. For example:
st2 --debug action list -p chatops
2017-04-05 00:56:01,935 DEBUG - Using cached token from file "/home/vagrant/.st2/token-st2admin"
# -------- begin 37703888 request ----------
curl -X GET -H 'Connection: keep-alive' -H 'Accept-Encoding: gzip, deflate' -H 'Accept: */*' -H 'User-Agent: python-requests/2.11.1' -H 'X-Auth-Token: b99d3f74a16e471992f2a10935637916' 'http://127.0.0.1:9101/v1/actions?pack=chatops'
# -------- begin 37703888 response ----------
[{"name": "format_execution_result", "parameters": {"execution_id": {"required": true, "type": "string", "description": "Id of execution to format"}}, "tags": [], "description": "Format an execution result for chatops", "enabled": true, "entry_point": "format_execution_result.py", "notify": {}, "uid": "action:chatops:format_execution_result", "pack": "chatops", "ref": "chatops.format_execution_result", "id": "58b7089ac4da5f6aa779b847", "runner_type": "python-script"}, {"name": "post_message", "parameters": {"extra": {"type": "object", "description": "Extra adapter-specific parameters."}, "whisper": {"default": false, "type": "boolean", "description": "Send a private message to user"}, "route": {"default": "chatops"}, "experimental": {"default": true, "immutable": true}, "user": {"type": "string", "description": "Explicitly notify a user"}, "message": {"required": true, "type": "string", "description": "Message to send."}, "channel": {"required": true, "type": "string", "description": "Channel to post to"}}, "tags": [], "description": "Post a message to stream for chatops", "enabled": true, "entry_point": "", "notify": {}, "uid": "action:chatops:post_message", "pack": "chatops", "ref": "chatops.post_message", "id": "58b7089ac4da5f6aa779b848", "runner_type": "announcement"}, {"name": "post_result", "parameters": {"whisper": {"default": false, "type": "boolean", "description": "Send a private message to user"}, "user": {"type": "string", "description": "Explicitly notify a user"}, "execution_id": {"required": true, "type": "string", "description": "ID of an execution to send"}, "channel": {"required": true, "type": "string", "description": "Channel to post to"}}, "tags": [], "description": "Post an execution result to stream for chatops", "enabled": true, "entry_point": "workflows/post_result.yaml", "notify": {}, "uid": "action:chatops:post_result", "pack": "chatops", "ref": "chatops.post_result", "id": "58b7089ac4da5f6aa779b849", "runner_type": "action-chain"}]
# -------- end 37703888 response ------------
+---------------------------------+---------+--------------------------------------------+
| ref | pack | description |
+---------------------------------+---------+--------------------------------------------+
| chatops.format_execution_result | chatops | Format an execution result for chatops |
| chatops.post_message | chatops | Post a message to stream for chatops |
| chatops.post_result | chatops | Post an execution result to stream for |
| | | chatops |
+---------------------------------+---------+--------------------------------------------+
NOTE: The URL displayed in the curl commands above is directly accessing the API service on port 9101. If you are connecting to the ST2 API from a remote system, you should modify this to work with Nginx on port 443. In the above output, http://127.0.0.1:9101/v1/actions?pack=chatops would become https://myhost.example.com/api/v1/actions?pack=chatops.
API errors have a standard HTTP response code, and a human-readable message. For example, if you try to create a rule with the same name as an existing rule, you will see an HTTP 409 response:
< HTTP/1.1 409 Conflict
< Server: nginx/1.10.3
< Date: Wed, 05 Apr 2017 00:44:32 GMT
< Content-Type: application/json
< Content-Length: 230
< Connection: keep-alive
< Access-Control-Allow-Origin: http://127.0.0.1:3000
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Auth-Token,St2-Api-Key,X-Request-ID
< Access-Control-Expose-Headers: Content-Type,X-Limit,X-Total-Count,X-Request-ID
< X-Request-ID: 68de2f2a-6fc0-4827-9ee9-b7124553d3e8
<
{
"conflict-id": "58e43d58c4da5f35c286a81f",
"faultstring": "Tried to save duplicate unique keys (E11000 duplicate key error collection: st2.rule_d_b index: uid_1 dup key: { : \"rule:examples:sample_rule_with_timer\" })"
}
4xx codes indicate a bad request, whereas 5xx errors indicate a server-side problem with StackStorm.
Join our Slack Community to get help from the engineering team and fellow users. You can also create issues against the main StackStorm GitHub repo, or the st2apidocs repo for documentation-specific issues.
We also recommend reviewing the main StackStorm documentation.