--- title: API examples description: This article provides examples of how to use the Cydarm API. --- [Skip to content](https://support.cydarm.com/en/knowledge/api-examples#main-content) English Show submenu for translations [More support](https://support.cydarm.com/en/knowledge/kb-tickets/new?hsLang=en) [Customer portal](https://support.cydarm.com/tickets-view?hsLang=en) ![Cydarm Logo](https://support.cydarm.com/hs-fs/hubfs/cydarm%202024%20logo%20blue%20on%20transparent%201000x250%20(3).png?width=200&height=50&name=cydarm%202024%20logo%20blue%20on%20transparent%201000x250%20(3).png) Open main navigation Close main navigation - English Show submenu for translations - [More support](https://support.cydarm.com/en/knowledge/kb-tickets/new) - [Customer portal](https://support.cydarm.com/tickets-view) - Contact us Contact us How can we help you? - There are no suggestions because the search field is empty. 1. [Knowledge Base](https://support.cydarm.com/en/knowledge?hsLang=en) 2. [Cydarm Administration](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en) 3. [API](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#api) # API examples ## This article provides examples of how to use the Cydarm API. ### Overview Here are some example API operations. This is current as of Cydarm 0.8.27. Interaction with the API requires an authenticated session. This can be done using a regular user account, or via a service account. For production use it is recommended to [create a service account.](https://support-staging.cydarm.com/en/knowledge/create-a-new-user-account?hsLang=en) Note that you cannot use an SSO account.  ### Start a session (login) and create an API key To start a session, username and password need to be base64 encoded and put into a JSON payload, and posted to `/cydarm-api/auth/password`. On successful auth, a response will be returned with a JWT authorisation (authz) token in the header **Access-Token**. This access token header needs to be included with all other requests. As the authz token is a long string, we represent it as "eyJhbGci..." or $bearerToken from here on in. If authentication is successful, a HTTP 200 response code will be issued. If the password is incorrect, a 401 Unauthorized will be returned. Other response codes may indicate a malformed payload.  Shell script: ``` encUserName=$(echo -n username | base64)encPassword=$(echo -n password | base64)bearerToken=$(curl -i -k  https://stackname.cydarm.com/cydarm-api/auth/password -d '{"username":"'$encUserName'", "password":"'$encPassword'"}'  | grep -i -E 'Access-Token: ' | cut -d ' ' -f 2- ) ``` Python: ``` import requestsbaseUrl="https://stackname.cydarm.com"def authenticate(fuser, fpass):    "authenticate to get an auth token, to use in subsequent API interactions in the X-Cydarm-Authz header"    params = dict(        username=str(base64.b64encode(fuser.encode('utf-8')), 'utf-8'),        password=str(base64.b64encode(fpass.encode('utf-8')), 'utf-8')    )    authUrl='%s/cydarm-api/auth/password' % baseUrl    logging.info("Authenticating to: {}".format(authUrl))    result = requests.post(authUrl, json=params)    if(result.status_code != 200):        bearerToken=-1        logging.error("Error. HTTP response: {}".format(result.status_code))        logging.error("headers: {}".format(result.headers))    else:        logging.info("Success. HTTP response: {}".format(result.status_code))        logging.info("headers: {}".format(result.headers))        bearerToken=result.headers['Access-Token']    return bearerToken ``` PowerShell: ``` $un=""$pw=""$baseUrl="https://.cydarm.com"function authenticate { param(   $username,   $password,   $url ) $cydarmAuthEndpoint = $baseUrl + "/cydarm-api/auth/password"   $cydarmAuthTokenPostParams = @{   username=[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($un))     password=[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($pw)) } | ConvertTo-Json   $cydarmAuthRes = Invoke-WebRequest -Uri $cydarmAuthEndpoint -ContentType "application/json" -Method Post -Body $cydarmAuthTokenPostParams   return $cydarmAccessToken=$cydarmAuthRes.Headers."Access-Token"}$bearertoken = authenticate -username $un -password $pw -url $cydarmURL ``` ### End a session (logout) This operation requires extracting the session UUID from the authz token, which can be done as follows: ``` echo $bearerToken | cut -d '.' -f 2 | sed -e 's/$/===/g' | base64 -D | jq .jti | tr -d '"' ``` Now we can logout using the session UUID: ``` curl -i -k -H "x-cydarm-authz: eyJhbGci..." https://stackname.cydarm.com/cydarm-api/auth/session/62d83efa-3a0e-4a45-b8dc-5412c151fd4e -X DELETE ``` ### Create a case ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case -d "{\"description\":\"name of new case\"}" ``` ### Add a tag to a case ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/tag -d "{\"caseUuid\":\"55131c1a-8c20-45dd-8722-f06550b9ccd3\",\"tagValue\":\"name-of-tag\"}" ``` ### Update the severity of a case This is an update so requires a PUT. Note also that the severity field is an integer, not a string, usually from 1 (Emergency) to 5 (Low). ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3 -d "{\"severity\":4}" -X PUT ``` ### Add a comment to a case This example uses the default ACL for the case. ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data -d "{\"data\":\"aGVsbG8gd29ybGQ=\",\"mimeType\":\"text/plain\",\"significance\":\"Comment\"}" ``` ### Upload a file to a case Note that *data* is the actual contents of the file, and *fileLastMod* is UNIX time, ie. seconds since 1970-01-01T00:00:00+00:00. ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data -d "{\"data\":\"aGVsbG8gd29ybGQK\",\"mimeType\":\"text/plain\",\"fileName\":\"hello.txt\",\"fileLastMod\":1567489274,\"significance\":\"Comment\"}" ``` ### Set the status of a case ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3 -d "{\"status\":\"Contain\"}" -X PUT ``` ### Add Members to a Case Note that the case group is the first UUID and the member is the second UUID. ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/member/09cf3b4a-fc85-4d3b-8dab-60ad5ff04f1d -X POST ``` ### Add a reply to a comment Note that the first UUID is the case UUID (as per adding a comment to a case) and the second UUID is the UUID of the comment we are replying to. ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data/3d886ba2-9023-4969-b4d4-101c75b1ea12 -d "{\"data\":\"aGVsbG8gd29ybGQ=\",\"mimeType\":\"text/plain\",\"significance\":\"Comment\"}" ``` Also note that in future API versions, replies will be submitted against */data/{dataUuid}* rather than */case/{caseUuid}/data/{dataUuid}*, as the *caseUuid* is redundant. ### Add a playbook to a case Note that the first UUID is the case UUID and the second is the playbook UUID. ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/playbook/33c2ba93-0df1-4ea5-bcc8-cb123bbbe993 -X POST ``` ### List cases (with filtering and sorting) ``` curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case?page%5bnumber%5d=0&page%5bsize%5d=5&filter%5bcreate_start%5d=2022-12-05T00%3A00%3A00.000Z&filter%5bseverity%5d=Low,Medium ``` Python: ``` authHeader = {"X-Cydarm-Authz": "{}".format(bearerToken) }# need to manually URL encode '+' end=DT.datetime.now().astimezone().replace(microsecond=0).isoformat().replace("+","%2B")start=(DT.datetime.now()-DT.timedelta(days=7)).astimezone().replace(microsecond=0).isoformat().replace    ("+","%2B")# use this token to get a list of all cases in the last 7 daysrequestUrl="{}/cydarm-api/case?page[number]=0&page[size]=999&filter[create_start]={}&filter[create_end]={}&filter[org]={}".format(baseUrl, start", end, args.org)result = requests.get(requestUrl, headers = authHeader)result_data=json.loads(result.content)['data'] ``` ### Notes for inputs - must include \`page\[number\]\` and \`page\[size\]\` - split by ',' into arrays (no spaces) - ie. \`filter\[severity\]=Low,Medium\` - Timestamps are in ISO8601 format - eg 2022-12-28T06:17:44Z (UTC time) - 2022-12-28T16:18:07+10:00 (AEST) - URL encoded - ie. \`filter\[create\_start\]=2022-01-01T00:00:00.000Z\` becomes: \`filter%5bcreate\_start%5d=2022-12-05T00%3A00%3A00.000Z\` #### **Current set of parameters available** | param | description | | --- | --- | | page\[number\] | The page offset to retrieve. | | page\[size\] | The number of items per page. | | filter\[create\_start\] | Earliest creation timestamp | | filter\[create\_end\] | Latest creation timestamp | | filter\[mod\_start\] | Earliest modification timestamp | | filter\[mod\_end\] | Latest modification timestamp | | filter\[state\] | Comma-delimited list of state names | | filter\[org\] | Comma-delimited list of org names | | filter\[assignee\] | Comma-delimited list of assignee names | | filter\[severity\] | Comma-delimited list of severity names | | filter\[inc\_tag\] | Comma-delimited list of tags to include | | filter\[exc\_tag\] | Comma-delimited list of tags to exclude | | filter\[text\] | Note: currently not implemented, due for implementation, due for implementation in July 2023 Text to search for in case locator, description, and metadata values | | filter\[parent\] |   | | sort | Field to sort on, one of: description, created, modified, org, assignee, status, severity, severity\_name, min\_sla\_name, min\_sla\_seconds, closed, actions, completed\_actions | | sort\_dir | Sort direction, one of asc or desc |   For more information, refer to our [Cydarm API documentation.](https://support.cydarm.com/en/knowledge/api-documentation?hsLang=en) - [General](https://support.cydarm.com/en/knowledge/general?hsLang=en#main-content) - [User Guides](https://support.cydarm.com/en/knowledge/general?hsLang=en#user-guides) - [Updates & Release Notes](https://support.cydarm.com/en/knowledge/general?hsLang=en#updates-release-notes) - [Playbooks](https://support.cydarm.com/en/knowledge/general?hsLang=en#playbooks) - [Cydarm Administration](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#main-content) - [Authentication](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#authentication) - [Application Administration](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#application-administration) - [Integrations](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#integrations) - [API](https://support.cydarm.com/en/knowledge/cydarm-administration?hsLang=en#api) [![Cydarm Logo](https://support.cydarm.com/hs-fs/hubfs/cydarm%202024%20logo%20blue%20on%20transparent%201000x250%20(3).png?width=200&height=50&name=cydarm%202024%20logo%20blue%20on%20transparent%201000x250%20(3).png "Cydarm Logo")](http://cydarm.com) [mailto:email@email.com](mailto:email@email.com) Copyright © 2026, Cydarm Technologies