API Reference

The samdesk API is organized around REST.

API Endpoint

https://api.samdesk.io/1/

Authentication

In order to authenticate with the samdesk API you must provide your Account's API Key.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

API Key

To obtain an API Key you must be an admin on your samdesk account and your account must have API access enabled. Navigate to your Settings page from within samdesk and go to the tab titled "API Access". From there click "Generate API Key" to generate an API key.

To use your API Key, simply append it to the request url as a querystring parameter with the key api_key.

To use your API Key, include it in the params dictionary with the key, "api_key".

To use your API Key, you need only call SAM::setAuth() with your key. The PHP library will automatically send this key in each request.

To use your API Key, you need only call sam.setAuth() with your key. The Node.js library will automatically send this key in each request.

To use your API Key, you need only call samClient.SetAuth() with your key. The .NET library will automatically send this key in each request.


curl https://api.samdesk.io/1/account?api_key={API_KEY}


requests.get("https://api.samdesk.io/1/account", params={'api_key': API_KEY})


samdesk::setAuth(array("api_key" => {API_KEY}));


sam.setAuth({ api_key: {API_KEY} });


samClient.SetAuth(AuthType.API_KEY, {API_KEY});

Errors

Samdesk uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error with the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with the samdesk servers.

Attributes

type: The type of error returned. Can be invalid_request_error or api_error.
message: A human-readable message giving more details about the error.
param: optional The parameter the error relates to if the error is parameter-specific.

HTTP Status Code Summary

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
404 Not Found - The requested item doesn't exist.
500 Internal Server Error - Something went wrong on samdesk's end.

Errors

Types

invalid_request_error	Invalid request errors arise when your request has invalid parameters.
api_error	API errors cover any other type of problem (e.g. a temporary problem with samdesk's servers) and should turn up only very infrequently.

Lists

Whenever the samdesk API needs to return a list of results, it returns a List object with the following properties

List Properties

count: integer The number of items in the List.
data: array An array containing the actual response data.
pagination: object An object containing the pagination information.


curl https://api.samdesk.io/1/search_streams?api_key={API_KEY}


requests.get("https://api.samdesk.io/1/search_streams", params={'api_key': API_KEY})


samdesk_Story::all();


sam.stories.list();


samClient.ListStories();


{
  "count": 2,
  "data": [{
    "id": "5bc4e88d91c06d00076d5482",
    ...
  }, {
    "id": "5bc4e88d91c06d00076d5483",
    ...
  }],
  "pagination": {
    "min_id": "5bc4e88d91c06d00076d5482",
    "max_id": "5bc4e88d91c06d00076d5483",
    "prev": "https://api.samdesk.io/1/search_streams?api_key={API_KEY}&min_id=5bc4e88d91c06d00076d5482",
    "next": "https://api.samdesk.io/1/search_streams?api_key={API_KEY}&max_id=5bc4e88d91c06d00076d5483"
  }
}

Response Formats

By default the samdesk API returns data as JSON. However, it is possible to request the data in other formats as well. To do so, simply append the format to the end of the request url like you would a file extension. For example,

https://api.samdesk.io/1/account.xml?api_key={API_KEY}

will return the Account data as XML. The supported formats are as follows:

Supported Formats

JSON: .json (default)
XML: .xml

Account

This is an object representing a samdesk Account. You can retrieve it to see properties of an Account like its name or tags.

Retrieve an Account

Retrieves the details of an Account.

Arguments

No Arguments

Returns

Returns an account object for the API key used.


GET https://api.samdesk.io/1/account


GET https://api.samdesk.io/1/account


samdesk_Account::retrieve();


sam.account.fetch();


samClient.RetrieveAccount();


curl https://api.samdesk.io/1/account?api_key={API_KEY}


requests.get("https://api.samdesk.io/1/account", params={'api_key': API_KEY})


samdesk::setAuth(array("api_key" => {API_KEY}));
samdesk_Account::retrieve();


var sam = require('sam-node')({ api_key: {API_KEY} });
sam.account.fetch(function(err, account) {
  // asynchronously called
});


var samClient = new SamClient(AuthType.API_KEY, {API_KEY});
samClient.RetrieveAccount();


{
  "id": "account1",
  "name": "Account 1",
  "status": "", //deprecated
  "tags": {
    "count": 2,
    "data": [{
      "name": "tag1",
      "color": "none"
    }, {
      "name": "tag2",
      "color": "red"
    }]
  }
}

List Account Users

Lists all of the Users in an Account.

Arguments

No Arguments

Returns

A List of User objects.


GET https://api.samdesk.io/1/account/users


GET https://api.samdesk.io/1/account/users


samdesk_Account::users();


sam.account.users();


samClient.ListAccountUsers();


curl https://api.samdesk.io/1/account/users?api_key={API_KEY}


requests.get("https://api.samdesk.io/1/account/users", params={'api_key': API_KEY})


samdesk::setAuth(array("api_key" => {API_KEY}));
samdesk_Account::users();


var sam = require('sam-node')({ api_key: {API_KEY} });
sam.account.users(function(err, users) {
  // asynchronously called
});


var samClient = new SamClient(AuthType.API_KEY, {API_KEY});
samClient.ListAccountUsers();


{
  "count": 2,
  "data": [{
    "id": "54cc0028dc7dd10f4b78d244",
    "name": "Sam Desk",
    "avatar_url": "https://app.samdesk.io/users/54cc0028dc7dd10f4b78d244/profile_pic"
  }, {
    "id": "54cc0028dc7dd10f4b78d245",
    "name": "Sam Chair",
    "avatar_url": "https://app.samdesk.io/users/54cc0028dc7dd10f4b78d245/profile_pic"
  }]
}

Alerts

This is an object representing an Alert for a samdesk Event.

Search Streams Alerts

Get a list of Alerts for a Search Stream.

NOTE: This endpoint will only return the last 1000 Alerts, or the last 30 days of Alerts, for the given Stream, whichever is smaller.

Arguments

count: optional The number of Alerts to return. Must be a number between 1 and 50, inclusive (default 20).
before: optional A timestamp in the form of MS since epoch. If provided, will only return Alerts that were created before that date.
after: optional A timestamp in the form of MS since epoch. If provided, will only return Alerts that were created after that date.
dashboard_only: optional By default this endpoint will return all incident updates that happen internally. To return only updates that you see in the dashboard set { dashboard_only: true }.

Returns

A List of Alert objects (see example response).

Note: return values for "alert_type" are as follows:

- "new"
- "update"

Note: return values for "severity" are as follows:

- "high"
- "medium"
- "low"
- "unknown"

Note: return values for "granularity" are as follows:

- "country"
- "admin_1"
- "admin_2"
- "admin_3"
- "admin_4"
- "admin_5"
- "locality"
- "sublocality_1"
- "sublocality_2"
- "sublocality_3"
- "sublocality_4"
- "sublocality_5"
- "neighbourhood"
- "place"

Note: return values for proximity_matches distance is in meters

Webhooks

It is also possible to set up a Webhook URL where samdesk will HTTP POST all new Alerts for the configured Stream to (with the data formatted the same as the Get Search Streams Alerts endpoint).

You can configure the Webhooks to send a custom HTTP header by setting the Header Key and Header Value properties when configuring the Webhook. Any Webhook POST requests will then include that header key and value along with the request. You can use this header then to verify that the requests are coming from samdesk and not some malicious source.

NOTE: Webhooks must be enabled for your account before you will be able to configure them. If you do not see the option to configure Webhooks then please contact your Account Manager to get that enabled.

An Account admin must go to the Account Integrations page to pre-configure a Webhook. Once that is done, any user in the Account can edit a Stream, toggle on "Webhook notifications", then select one of the pre-configured Webhooks from the dropdown.


GET https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts


GET https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts

todo todo todo


curl https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts?api_key={API_KEY}


requests.get(f"https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts", params={'api_key': API_KEY})

todo todo todo


{
  "count": 1,
  "data": [{
    "id": 6bc4e89d91c06d00076d5412,
    "alert_type": "update",
    "alert_text": "Two people now known to be injured.",
    "created": 1411523640000,
    "event": {
      "id": "5bc4e88d91c06d00076d5482",
      "severity": "medium",
      "headline": "Reports of a low severity Fire detected in Trump Tower, New York, New York, USA",
      "summary_text": "A fire has been reported in New York.",
      "types": [
        "Fire"
      ],
      "tags": [
        "Hospital"
      ],
      "locations": [{
        "text": "New York, New York, USA",
        "granularity": "locality",
        "lat": 40.7624,
        "lng": -73.9738
      }],
      "polygons": [
        "-115.9811,54.8067 -116.4279,54.1879 -117.5281,54.0883 -117.5267,54.5875 -115.9811,54.8067"
      ],
      "time": 1411523640000,
      "topics": [{
        "topic": "Emergency and Safety",
        "subtopics": ["Urgent and Developing"],
      }],
      "updates": [{
        "time" : 1660454498413,
        "type" : "post",
        "social_type" : "twitter",
        "public_id" : "1558685025440243712",
      }],
      "proximity_matches": [{
        "lat" : 40.7506,
        "lng" : -73.9923,
        "name" : "Lego Store 5th Ave",
        "distance" : 643,
        "asset_type" : "place",
        "is_exact_match" : false
      }]
    }
  }],
  "pagination": {
    "before": 1665317357998,
    "next": "https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts?api_key={API_KEY}&before=1665317357998",
    "after": 1665514848900,
    "prev": "https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/alerts?api_key={API_KEY}&after=1665514848900"
  }
}