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"
  }]
}

Events

This is an object representing a samdesk Event.

Search Streams

Get a list of Search Streams for an Account.

Arguments

count: optional The number of Search Streams to return. Must be a number between 1 and 50, inclusive (default 50).
user: optional A User ID to filter Search Streams by. If provided, will only return Search Streams belonging to the specified User. Note: this parameter is only valid when using api_key.
max_id: optional A Search Stream ID. If provided, will only return Search Streams after the given ID. Note: Only one of max_id and min_id may be provided.
min_id: optional A Search Stream ID. If provided, will only return Search Streams before the given ID. Note: Only one of max_id and min_id may be provided.

Returns

A List of Search Stream objects (see example response).


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


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

todo todo todo


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


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

todo todo todo


{
  "count": 1,
  "data": [{
    "id": "5bc4e88d91c06d00076d5482",
    "name": "Global Stream",
    "created": 1411523640000,
    "updated": 1411523640000,
    "user": {
      "id": "5bc4e88d91c06d00076d5483",
      "name": "John Doe"
    }
  }, {
  "pagination": {
    "max_id": "5bc4e88d91c06d00076d5482",
    "next": "https://api.samdesk.io/1/search_streams?api_key={API_KEY}&max_id=5bc4e3e69f859600073e232a",
    "min_id": "5bc4e88d91c06d00076d5482",
    "prev": "https://api.samdesk.io/1/search_streams?api_key={API_KEY}&min_id=5bc4e88d91c06d00076d5482"
  }
}

Search Stream Events

List the Events for a Search Stream with the given ID.
To obtain a Search Stream ID open samdesk and create one.

NOTE: This endpoint will only return Events from the last 30 days.

NOTE: The behaviour of the endpoint is slightly different for V2 streams. In short, it is possible for the results from paging backwards (using the updated_before parameter) to include Events that have been updated after the provided updated_before date. Because of this inconsistency we recommend migrating to the Search Streams Alerts endpoint for V2 Streams.

Arguments

search_stream_id: required ID of the Search Stream.
count: optional The number of Events to return. Must be a number between 1 and 50, inclusive (default 50).
max_id: optional An Event ID. If provided, will only return Events that have alerted before the Event with the given ID.
Note: Only one of max_id and min_id may be provided.
Note: The max_id parameter has been deprecated for V2 Streams. Please use updated_after instead.
min_id: optional An Event ID. If provided, will only return Events that have alerted after the Event with the given ID.
Note: Only one of max_id and min_id may be provided.
Note: The min_id parameter has been deprecated for V2 Streams. Please use updated_before instead.
updated: optional (deprecated) A timestamp in the form of MS since epoch. If provided, will only return Events that have last updated since that date.
Note: Cannot be provided alongside min_id or max_id.
updated_before: optional A timestamp in the form of MS since epoch. If provided, will only return Events that have last updated before that date.
Note: Cannot be provided alongside min_id or max_id.
updated_after: optional A timestamp in the form of MS since epoch. If provided, will only return Events that have last updated after that date.
Note: Cannot be provided alongside min_id or max_id.
include_dismissed: optional If "true", the response will include Events that have been dismissed.

Returns

A List of Event objects (see example responses, subject to restrictions for public sector clients).

Note: By default the returned list of Event objects will be sorted in descending order by `time` (alert time). If an `updated` cursor is provided (updated, updated_before, updated_after), however, the returned list of Event objects will be sorted in descending order by `updated`.

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

- "detected"
- "dismissed"

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 inside of the "source_labels" array are as follows:

- "official"
- "news"

Note: return values for proximity_matches distance is in meters


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


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

todo todo todo


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


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

todo todo todo


{
  "count": 1,
  "data": [{
    "id": "5bc4e88d91c06d00076d5482",
    "status": "detected",
    "severity": "medium",
    "types": [
      "Fire"
    ],
    "tags": [
      "Hospital"
    ],
    "location": "Trump Tower, New York, New York, USA",
    "granularity": "place",
    "geo": {
      "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"
    ],
    "locations": [{
      "text": "New York, New York, USA",
      "granularity": "locality",
      "lat": 40.7624,
      "lng": -73.9738
    }],
    "time": 1411523640000,
    "updated": 1411523640000,
    "total_posts": 144,
    "first_post": {
      "social_type": "twitter",
      "public_id": "1051861686842474496"
    },
    "trigger_post": {
      "social_type": "twitter",
      "public_id": "1051861686842474496"
    },
    "feature_post": {
      "social_type": "twitter",
      "public_id": "1051861686842474496"
    },
    "headline": "Reports of a low severity Fire detected in Trump Tower, New York, New York, USA",
    "topics": [{
      "topic": "Emergency and Safety",
      "subtopics": ["Urgent and Developing"],
    }],
    "updates": [
        {
            "time" : 1660454498413,
            "type" : "post",
            "text" : "Pedestrian incident injures at least one at 66 Street & 130 Avenue, Edmonton, Alberta, per news report",
            "social_type" : "twitter",
            "public_id" : "1558685025440243712",
        },
        {
            "time" : 1660508787360,
            "type" : "post",
            "text" : "Crash in Edmonton, Alberta, per local source",
            "social_type" : "reddit",
            "public_id" : "t3_woftrr",
        },
        {
            "time" : 1660598331226,
            "type" : "note",
            "text" : "Two pedestrians were struck by a car today at 1PM at 66 Street & 130 Avenue in Edmonton, Alberta",
        },
    ],
    "source_labels": [
      "official"
    ],
    "proximity_matches": [{
        "lat" : 40.7506,
        "lng" : -73.9923,
        "name" : "Lego Store 5th Ave",
        "distance" : 643,
        "asset_type" : "place",
        "is_exact_match" : true
    }],
    "dismissed_date": undefined,
    "merged_into": undefined,
  }],
  "pagination": {
    "prev": "https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/events?api_key={API_KEY}&min_id=5bc4e88d91c06d00076d5482",
    "max_id": "5bc4e88d91c06d00076d5482",
    "min_id": "5bc4e88d91c06d00076d5482",
    "next": "https://api.samdesk.io/1/search_streams/{SEARCH_STREAM_ID}/events?api_key={API_KEY}&max_id=5bc4e88d91c06d00076d5482"
  }
}

Event Posts

List the Posts for the Search Stream Event with the given ID. This method isn't available for public sector accounts.

Arguments

event_id: required ID of the Search Stream Event.
count: optional The number of Posts to return. Must be a number between 1 and 50, inclusive (default 50).
direction: optional The direction to return the Posts in based on posted date. Must be one of 'asc' (ascending) or 'desc' (descending) (default 'asc').
max_id: optional A Post ID. If provided, will only return Posts after the given ID. Note: Only one of max_id and min_id may be provided.
min_id: optional A Post ID. If provided, will only return Posts before the given ID. Note: Only one of max_id and min_id may be provided.

Returns

A List of Post objects (see example response).

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

- "official"
- "news"
- ""

Note: return values for "polygons" are counter-clockwise rings with longitude/latitude coordinate pairs in accordance with GeoJSON standards.


GET https://api.samdesk.io/1/events/{EVENT_ID}/posts


GET https://api.samdesk.io/1/events/{EVENT_ID}/posts

todo todo todo


curl https://api.samdesk.io/1/events/{EVENT_ID}/posts?api_key={API_KEY}


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

todo todo todo


{
  "count": 2,
  "data": [{
    "id": "5bc4e88d91c06d00076d5482",
    "social_type": "twitter",
    "public_id": "1051861686842474496",
    "source_label": "news"
  }, {
    "id": "5bc4e3e69f859600073e232a",
    "social_type": "twitter",
    "public_id": "1051861686842474487",
    "source_label": ""
  }],
  "pagination": {
    "max_id": "5bc4e3e69f859600073e232a",
    "next": "https://api.samdesk.io/1/events/{EVENT_ID}/posts?api_key={API_KEY}&max_id=5bc4e3e69f859600073e232a",
    "min_id": "5bc4e88d91c06d00076d5482",
    "prev": "https://api.samdesk.io/1/events/{EVENT_ID}/posts?api_key={API_KEY}&min_id=5bc4e88d91c06d00076d5482"  "count":
  }
}

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.

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.

https://app.samdesk.io: When configuring notifications for a Stream you can toggle on "Webhook notifications" and provide the Webhook configuration there.

https://dash.samdesk.io: 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",
      "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"
  }
}