API Newbie Question

I would like to pull a list of the categories in SWSD we have so far. Support directed me to use an API. I do not have experience with using an api to pull data. Can anyone direct me on how to get started and connect to our database?


  • Hearing that you need to pull from the API can be intimidating. It will be easier than you think, use the links to dig into stuff I mention.

    First do you have curl? Its not in windows by default, and the examples provided use it. I downloaded the version for windows.

    The documentation is good, and accurate, but might read like a foreign language to you.


    To start go to your instance, find your user account and generate the token you need. In all of the curl examples TOKEN gets replaced by that enormous string they give you. Save that off somewhere so you can copy and paste it as you need.

    Now that you have the key to get inside the API, you can use the commands they provide. Category docs are here:

    And the command they give to list them is:
    curl -H "X-Samanage-Authorization: Bearer TOKEN" -H 'Accept: application/xml' -H 'Content-Type:text/xml' -X GET api.samanage.com/.../CATEGORY_ID.xml

    Swap out TOKEN for the token you just made and if curl is in the path you can use that command exactly (or provide the full path to the .exe)
    It will look a little like this. (Data is from a test instance, and the automatically generated categories.)

    If you want a text file with that data, just add something like  > ''c:\folders\output.xml" to the end to get the results in a text file.

    I don't ever use curl, I don't want my data like this. I use PowerShell. And I google extensively for examples when I get confused, which I think is standard for most of us who don't work with API's daily.

    $token = 'TOKEN'
    $apiRoot = "https://api.samanage.com"
    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $headers.Add("Accept", 'application/vnd.samanage.v2.1+json')
    $headers.Add("X-Samanage-Authorization", "Bearer $token")
    $contentType = "application/json"
    $response = Invoke-RestMethod -Uri "$apiRoot/categories.json" -Headers $headers -ContentType $contentType -Method Get

    Again, replace TOKEN, and at the end of it you have a variable $response with your results.  I sent the results to a grid with" $response | OGV

    You can see that there are parent and children objects, and you can work on those like anything else in PowerShell. You can send that data as output using lots of the built in commands. If need more assistance, let me know.

  • This is exactly the jump start I need. Thank you so much for your willingness to share! Slight smile

Reply Children