Introduction

Welcome to the Attensa API! To get started, please contact us about getting a developer account.

The Attensa API helps you manage your users and streams outside of our web interface. The API is split into 7 different sections:

Briefings - Get a list of active briefings.
Categories - Get and set information about stream categories, including streams and briefings that a category contains.
Groups - Get and set up user groups, including the streams and briefings a group subscribes to.
Items - Get information about items.
Streams - Create streams, get information about them and post new items into streams.
Stream Tags - Tag streams with labels and find them later.
Reports - Retrive a list of downloadable weekly reports on user activity.
Users - Set up new users, get information about users and subscribe users to streams.

Authentication

To authorize, pass your username and password using basic auth:

curl -u username:password https://api.attensa.net/endpoint

Attensa uses HTTP basic authentication. You can obtain a username and password by contacting us here.

HTTPS is required, we do not support HTTP.

Briefings

GET /briefings

curl -u username:password \
     -X GET \
     -d page=0 \
     -d rows=20 \
     https://api.attensa.net/briefings

Status code 200 with response as follows:

{
  "_paging": {
    "elementCount": 1,
    "page": 0,
    "pageCount": 1,
    "requestedPageSize": 20,
    "totalElementCount": 1
  },
  "_links": {
    "first": "https://api.attensa.net/briefings?rows=20&page=0",
    "last": "https://api.attensa.net/briefings?rows=20&page=0"
  },
  "briefings": [
    {
      "id": "546e17fcd4c88ef1547b4f33",
      "ownerId": "55414a36e4b0436b6280e668",
      "briefingTitle": "Daily Briefing Example",
      "templateTitle": "Title that can be used inside Templates via helpers",
      "description": "Daily news sent ever day.",
      "subject": "Your Daily News!",
      "templateId": "54eba226e4b050dd8b9c1099",
      "subscriberCount": 0,
      "schedule": {
        "frequency": "DAILY",
        "interval": 2,
        "sendHour": 10,
        "sendMinute": 30,
        "startDate": "2017-03-29",
        "timeZone": "US/Pacific"
      },
      "streamIds": [
        "55fae1c6e4b0efbbd6062867",
        "585206dbe4b06537eec79b04",
        "55e4e635e4b00de911f2259a"
      ]
    }
  ]
}

Get a paged list of all enabled briefings.

Request

GET /briefings

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of briefings in each page	No	Integer	20

Response

Status code 200

See the paging metadata specification for more information on the _paging property.

GET /briefings/{briefingId}

curl -u username:password https://api.attensa.net/briefings/{briefingId}

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c88ef1547b4f33",
  "ownerId": "55414a36e4b0436b6280e668",
  "briefingTitle": "Daily Briefing Example",
  "templateTitle": "Title that can be used inside Templates via helpers.",
  "description": "Daily news sent ever day.",
  "subject": "Your Daily News!",
  "templateId": "54eba226e4b050dd8b9c1099",
  "subscriberCount": 0,
  "schedule": {
    "frequency": "DAILY",
    "interval": 1,
    "sendHour": 10,
    "sendMinute": 30,
    "startDate": "2017-03-29",
    "timeZone": "US/Pacific"
    },
  "streams": [
    {
      "id": "546e17fcd4c67da2547f5b61",
      "categoryIds": [
        "54c67d6ee4b07a480d551f5c"
      ],
      "emailPostingEnabled": false,
      "followersCount": 1,
      "itemsCount": 373,
      "openForPosting": false,
      "openForReading": true,
      "ownerId": "54172bb3e4b0fc6238a83bdf",
      "published": true,
      "rssEnabled": false,
      "tagIds": [],
      "title": "Test Stream 01",
      "type": "RSS",
      "_links": {
        "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
        "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
      },
      "source": {
        "uri": "http://rss.example.com/example"
      }
    },
    {
      "id": "585206dbe4b06537eec79b04",
      "title": "Test Stream 02",
      "ownerId": "53dfb536e4b05bc54063f5f4",
      "categoryIds": [
        "55c100cce4b019471b4dbfa3"
      ],
      "emailPostingEnabled": false,
      "followersCount": 0,
      "itemsCount": 15296,
      "openForPosting": false,
      "openForReading": true,
      "published": true,
      "rssEnabled": false,
      "substreams": [
        {
          "id": "5568efd9e4b07710a6f08f7d",
          "title": "Example source stream Title",
          "type": "RSS"
        },
        {
          "id": "559e9e52e4b09bde8ba71aad",
          "title": "Example Topic Title",
          "type": "COLLECTION"
        }
      ],
      "tagIds": ["test"],
      "type": "COLLECTION",
      "_links": {
        "self": "https://api.attensa.net/streams/585206dbe4b06537eec79b04",
        "owner": "https://api.attensa.net/users/53dfb536e4b05bc54063f5f4"
      }
    }
  ],
  "_links": {
    "self": "https://api.attensa.net/briefings/546e17fcd4c88ef1547b4f33",
    "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
  }
}

This endpoint retrieves a specific briefing.

Request

GET https://api.attensa.net/briefings/{briefingId}

Response

Status code 200

GET /briefings/{briefingId}/preview

curl -u username:password https://api.attensa.net/briefings/{briefingId}/preview

The above command returns a preview of the raw HTML that would be used to send the briefing email:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
[SNIP]
</head>
<body width="100%" bgcolor="#f4f4f4" style="Margin: 0;">
[SNIP]
</body>
</html>

This endpoint retrieves a preview of a briefing’s HTML email.

Request

GET https://api.attensa.net/briefings/{briefingId}/preview

Response

Status code 200

GET /briefings/{briefingId}/streams

curl -u username:password \
     -X GET \
     -d page=0 \
     -d rows=20 \
     https://api.attensa.net/briefings/{briefingId}/streams

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/briefings/{briefingId}/streams?page=0&rows=20",
    "last": "https://api.attensa.net/briefings/{briefingId}/streams?page=0&page=20"
  },
  "streams": [{
    "id": "546e17fcd4c67da2547f5b61",
    "title": "Test Stream 01",
    "groupIsSubscribed": true,
    "description": "Description 01",
    "ownerId": "55414a36e4b0436b6280e668",
    "type": "COLLECTION",
    "emailPostingEnabled": true,
    "openForReading": true,
    "openForPosting": false,
    "published": true,
    "streamEmailAddress": "test.stream.01@email.attensa.net",
    "rssEnabled": false,
    "categoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
    "tagIds": ["54da78488ab02386a4658eee"],
    "substreams": [
      {
          "id": "559c1972e4b008b9a5329478",
          "title": "Hi, I am a substream!",
          "type": "RSS"
      }
    ],
    "_links": {
      "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
      "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
    }
  }]
}

Get a paged list of streams in the briefing.

Request

GET https://api.attensa.net/briefings/{briefingId}/streams

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of streams in each page	No	Integer	20

Response

Status code 200

See the paging metadata specification for more information on the _paging property

GET /briefings/{briefingId}/users

curl -u username:password https://api.attensa.net/briefings/{briefingId}/users

Status code 200 with json structured as follows:

{
  "_links": {
    "first": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=0",
    "last": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=1",
    "next": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=1"
  },
  "_paging": {
    "elementCount": 20,
    "page": 0,
    "pageCount": 2,
    "requestedPageSize": 20,
    "totalElementCount": 34
  },
  "users": [
    {
      "id": "5421903ae4b0fd12d843a219",
      "emailAddress": "test@attensa.com",
      "firstName": "Adam",
      "middleName": "J",
      "lastName": "Test",
      "suffix": "SR",
      "status": "ACTIVE",
      "timeZone": "US/Pacific",
      "_links": {
        "self": "https://api.attensa.net/users/5421903ae4b0fd12d843a219"
      }
    },
    ...
  ]
}

Get users that are subscribed to a specific briefing.

Request

GET https://api.attensa.net/briefings/{briefingId}/users

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of users returned	No	String	`null`
sort	Field to sort the results on	No	firstName, lastName or emailAddress	emailAddress
sortDirection	Sort ascending or descending	No	ASC or DESC	ASC

Response

Status code 200

POST /briefings

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "briefingTitle": "Briefing created via API",
       "templateTitle": "Special per briefing message!",
       "subject": "Your Daily Briefing",
       "description": "A briefing providing daily news updates.",
       "ownerId": "577699bae4b0caf6efc3fdfc",
       "schedule": {
           "startDate": "2017-04-13",
           "sendHour": 10,
           "sendMinute": 30,
           "frequency": "DAILY",
           "timeZone": "US/Pacific"
    },
    "templateId": "54b58250e4b0ec83add2661e",
    "streamIds": ["546e17fcd4c67da2547f5b61", "585206dbe4b06537eec79b04"]
}' \
     https://api.attensa.net/briefings

The above command returns JSON structured like this:

{
  "id": "586ee582e4b05458263553cf",
  "briefingTitle": "Briefing created via API",
  "templateTitle": "Special per briefing message!",
  "subject": "Your Daily Briefing",
  "description": "A briefing providing daily news updates.",
  "ownerId": "577699bae4b0caf6efc3fdfc",
  "templateId": "54b58250e4b0ec83add2661e",
  "subscribersCount": 0,
  "streams": [
    {
      "id": "546e17fcd4c67da2547f5b61",
      "categoryIds": [
        "54c67d6ee4b07a480d551f5c"
      ],
      "emailPostingEnabled": false,
      "followersCount": 1,
      "itemsCount": 373,
      "openForPosting": false,
      "openForReading": true,
      "ownerId": "55414a36e4b0436b6280e668",
      "published": true,
      "rssEnabled": false,
      "tagIds": [],
      "title": "Test Stream 01",
      "type": "RSS",
      "_links": {
        "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
        "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
      },
      "source": {
        "uri": "http://rss.example.com/example"
      }
    },
    {
      "id": "585206dbe4b06537eec79b04",
      "title": "Test Stream 02",
      "ownerId": "53dfb536e4b05bc54063f5f4",
      "categoryIds": [
        "55c100cce4b019471b4dbfa3"
      ],
      "emailPostingEnabled": false,
      "followersCount": 0,
      "itemsCount": 15296,
      "openForPosting": false,
      "openForReading": true,
      "published": true,
      "rssEnabled": false,
      "substreams": [
        {
          "id": "5568efd9e4b07710a6f08f7d",
          "title": "Example source stream Title",
          "type": "RSS"
        },
        {
          "id": "559e9e52e4b09bde8ba71aad",
          "title": "Example Topic Title",
          "type": "COLLECTION"
        }
      ],
      "tagIds": ["test"],
      "type": "COLLECTION",
      "_links": {
        "self": "https://api.attensa.net/streams/585206dbe4b06537eec79b04",
        "owner": "https://api.attensa.net/users/53dfb536e4b05bc54063f5f4"
      }
    }
  ],
  "schedule": {
    "startDate": "2017-04-13",
    "sendHour": 10,
    "sendMinute": 30,
    "interval": 1,
    "frequency": "DAILY",
    "timeZone": "US/Pacific"
  },
  "_links": {
    "self": "https://api.attensa.net/briefings/586ee582e4b05458263553cf",
    "owner": "https://api.attensa.net/users/577699bae4b0caf6efc3fdfc"
  }
}

Create a new briefing.

Request

POST https://api.attensa.net/briefings

JSON request properties

Parameter	Description	Required	Format	Default
briefingTitle	Briefing Title	Yes	String	n/a
templateTitle	Custome string for use in templates.	No	String	`null`
description	Long description of the briefing	No	String	`null`
ownerId	User id of briefing owner	Yes	String of valid user id	n/a
subject	Subject line used for sending briefing email	Yes	String	n/a
templateId	Email template to use	No	String of valid template id	id of default template
streamIds	Stream IDs to include in the briefing	No	[String]	[]
schedule:startDate	Day to start sending the briefing	Yes	`YYYY-MM-DD`	n/a
schedule:stopDate	Day to stop sending the briefing. Omit to never stop.	No	`YYYY-MM-DD`	`null`
schedule:sendHour	Hour of day to send briefing	Yes	Integer `0-23`	n/a
schedule:sendMinute	Minute of hour to send briefing	Yes	Integer `0-59`	n/a
schedule:frequency	Frequency to send briefing	Yes	`DAILY`, `WEEKLY`, `MONTHLY`	n/a
schedule:interval	Interval of frequency to send. e.g. send every `<interval>` days	No	Integer `1-31`	1
schedule:sendDays	Array of days of the week to send briefing on	For WEEKLY frequency	[`SU`,`MO`,`TU`,`WE`,`TH`,`FR`,`SA`]	n/a
schedule:timeZone	Timezone of requested send time	Yes	Supported time zone string	`null`

Response

Status code 201

PUT /briefings/{briefingId}

curl -u username:password \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "briefingTitle": "Updated Briefing Example",
       "templateTitle": "New special per briefing message!",
       "subject": "Your Daily Updated Briefing",
       "description": "An updatged briefing providing daily news updates.",
       "ownerId": "577699bae4b0caf6efc3fdfc",
       "schedule": {
           "sendHour": 11,
           "sendMinute": 30,
           "frequency": "WEEKLY",
           "sendDays":["MO", "WE", "FR"],
           "timeZone": "US/Pacific"
    },
    "templateId": "54eba226e4b050dd8b9c1099",
    "streamIds": ["546e17fcd4c67ef6622d3b22"]
}' \
     https://api.attensa.net/briefings/{briefingId}

The above command returns JSON structured like this:

{
  "id": "586ee582e4b05458263553cf",
  "briefingTitle": "Updated Briefing Example",
  "templateTitle": "New special per briefing message!",
  "subject": "Your Daily Updated Briefing",
  "description": "An updatged briefing providing daily news updates.",
  "ownerId": "577699bae4b0caf6efc3fdfc",
  "templateId": "54eba226e4b050dd8b9c1099",
  "subscribersCount": 0,
  "streams": [
    {
      "id": "546e17fcd4c67ef6622d3b22",
      "title": "Example Stream",
      "categoryIds": [
        "54c67d6ee4b07a480d551f5c"
      ],
      "emailPostingEnabled": false,
      "followersCount": 14,
      "itemsCount": 61,
      "openForPosting": false,
      "openForReading": true,
      "ownerId": "55414a36e4b0436b6280e668",
      "published": true,
      "rssEnabled": false,
      "tagIds": ["example"],
      "type": "RSS",
      "substreams": [
        {
          "id": "56d716c0e4b0372417948d9c",
          "title": "New target topic",
          "type": "COLLECTION"
        }
      ],
      "_links": {
        "self": "https://api.attensa.net/streams/546e17fcd4c67ef6622d3b22",
        "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
      },
      "source": {
        "uri": "http://rss.example.com/example"
      }
    }
  ],
  "schedule": {
    "startDate": "2017-04-13",
    "sendHour": 11,
    "sendMinute": 30,
    "interval": 1,
    "frequency": "WEEKLY",
    "sendDays":["MO", "WE", "FR"],
    "interval": 1,
    "timeZone": "US/Pacific"
  },
  "_links": {
    "self": "https://api.attensa.net/briefings/586ee582e4b05458263553cf",
    "owner": "https://api.attensa.net/users/577699bae4b0caf6efc3fdfc"
  }
}

Update an existing briefing. Updates are applied in a incremental PATCH-like manner, so the entire briefing resource does not need to be supplied, only the properties that are changing.

Request

PUT https://api.attensa.net/briefings/{briefingId}

JSON body request properties

Parameter	Description	Required	Format	Default
briefingTitle	Briefing Title	Yes	String	n/a
templateTitle	Custome string for use in templates.	No	String	`null`
description	Long description of the briefing	No	String	`null`
ownerId	User id of briefing owner	Yes	String of valid user id	n/a
subject	Subject line used for sending briefing email	Yes	String	n/a
templateId	Email template to use	No	String of valid template id	id of default template
streamIds	Stream IDs to include in the briefing	No	[String]	[]
schedule:startDate	Day to start sending the briefing	Yes	`YYYY-MM-DD`	n/a
schedule:sendHour	Hour of day to send briefing	Yes	Integer `0-23`	n/a
schedule:sendMinute	Minute of hour to send briefing	Yes	Integer `0-59`	n/a
schedule:frequency	Frequency to send briefing	Yes	`DAILY`, `WEEKLY`, `MONTHLY`	n/a
schedule:interval	Interval of frequency to send. e.g. send every `<interval>` days	No	Integer `1-31`	1
schedule:sendDays	Array of days of the week to send briefing on	For WEEKLY frequency	[`SU`,`MO`,`TU`,`WE`,`TH`,`FR`,`SA`]	n/a
schedule:timeZone	Timezone of requested send time	Yes	Supported time zone string	`null`

All streams can be removed by sending an empty streamIds array ("streamIds": [])

Response

Status code 200

DELETE /briefings/{briefingId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/briefings/{briefingId}

204 empty body returned on success

Delete an existing briefing from the system. All users will be unsubscribed from the briefing when it is deleted.

Request

DELETE https://api.attensa.net/briefings/{briefingId}

Response

Status code 204 with empty body

DELETE /briefings/{briefingId}/streams/{streamId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/briefings/{briefingId}/streams/{streamId}

204 empty body returned on success

Remove a stream from a briefing.

Request

DELETE https://api.attensa.net/briefings/{briefingId}/streams/{streamId}

Response

Status code 204 with empty body

DELETE /briefings/{briefingId}/users/{userId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/briefings/{briefingId}/users/{userId}

204 empty body returned on success

Unsubscribe a user from a briefing.

Request

DELETE https://api.attensa.net/briefings/{briefingId}/users/{userId}

Response

Status code 204 with empty body

Parameter	Description	Required	Format	Default
id	Id of existing category to update title	No	String	`null`
title	Title of the category.	Yes	String	n/a
subcategories	Array of subcategories	No	Array of objects with title and optional id	`null`

Groups

GET /groups

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     -d term=test \
     -d autoAddNewUsers=true \
     https://api.attensa.net/groups

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/groups?rows=20&page=0&term=test",
    "last": "https://api.attensa.net/groups?rows=20&page=0&term=test"
  },
  "groups": [
    {
      "creatorId": "56161che546097aa51621b47",
      "description": "foo",
      "name": "test",
      "streamCount": 5,
      "userCount": 192,
      "autoAddNewUsers": true,
      "_links": {
          "self": "https://api.attensa.net/groups/55161cf7e4b097aa51621b47"
      }
    }
  ]
}

Get a paged list of groups.

Request

GET https://api.attensa.net/groups

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of groups in each page	No	Integer	20
term	A search term to narrow the list of groups returned	No	String	`null`
autoAddNewUsers	Filters groups list to groups where autoAddNewUsers is set to true	No	Boolean	`null`

Response

Status code 200

GET /groups/{groupId}

curl -u username:password https://api.attensa.net/groups/{groupId}

Status code 200 with response as follows:

{
  "creatorId": "56161che546097aa51621b47",
  "description": "foo",
  "id": "55161cf7e4b097aa51621b47",
  "name": "test",
  "streamCount": 5,
  "userCount": 2,
  "_links": {
    "self": "http://localhost/groups/55161cf7e4b097aa51621b47"
  }
}

This endpoint retrieves information about a specific group.

Request

GET https://api.attensa.net/groups/{groupsId}

Response

Status code 200

GET /groups/{groupId}/users

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     -d sort=firstName
     -d sortDirection=ASC
     -d term=test \
     https://api.attensa.net/groups/{groupId}/users

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/groups/{groupId}/users?rows=20&page=0&term=test&sort=firstName&sortDirection=ASC",
    "last": "https://api.attensa.net/groups/{groupId}/users?rows=20&page=0&term=test&sort=firstName&sortDirection=ASC"
  },
  "users": [
    {
      "id": "546e17fcd4c67da2547f5b61",
      "firstName": "test",
      "middleName": "j",
      "lastName": "user",
      "suffix": "sr",
      "emailAddress": "foo@test.com",
      "timeZone": "Europe/Paris",
      "status": "ACTIVE",
      "_links": {
        "self": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61"
      }
    }
  ]
}

This endpoint retrieves a paged list of users in a certain group.

Request

GET https://api.attensa.net/users

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of users returned	No	String	`null`
sort	Field to sort the results on	No	`firstName`, `lastName`, `emailAddress`, `status`	emailAddress
sortDirection	Sort ascending or descending	No	ASC or DESC	ASC

Response

Status code 200

See the paging metadata specification for more information on the _paging property

GET /groups/{groupId}/streams

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     -d term=test \
     https://api.attensa.net/groups/{groupId}/streams

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/groups/{groupId}/streams?rows=20&page=0&term=test",
    "last": "https://api.attensa.net/groups/{groupId}/streams?rows=20&page=0&term=test"
  },
  "streams": [{
    "title": "Test Stream 01",
    "description": "Description 01",
    "ownerId": "55414a36e4b0436b6280e668",
    "type": "COLLECTION",
    "emailPostingEnabled": true,
    "openForReading": true,
    "openForPosting": true,
    "published": true,
    "streamEmailAddress": "test.stream.01@email.attensa.net",
    "substreams":[
      {
        "id": "559c1972e4b008b9a5329478",
        "title": "Hi, I am a substream!",
        "type": "RSS"
      }
    ],
    "tagIds": ["54da78488ab02386a4658eee"],
    "rssEnabled": false,
    "categoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"]
  }]
}

This endpoint retrieves a paged list of streams that a group follows.

Request

GET https://api.attensa.net/streams

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of streams in each page	No	Integer	20
term	A search term to narrow the list of streams returned	No	String	`null`

Response

Status code 200

See the paging metadata specification for more information on the _paging property

GET /groups/{groupId}/briefings

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     https://api.attensa.net/groups/{groupId}/briefings

The above command returns JSON structured like this:

{
  "_paging": {
    "elementCount": 1,
    "page": 0,
    "pageCount": 1,
    "requestedPageSize": 20,
    "totalElementCount": 1
  },
  "_links": {
    "first": "https://api.attensa.net/groups/{groupId}/briefings?rows=20&page=0",
    "last": "https://api.attensa.net/groups/{groupId}/briefings?rows=20&page=0"
  },
  "briefings": [
    {
      "subject": "My email subject line!",
      "description": "Some special message used by template.",
      "schedule": {
          "startDate": "2015-07-30",
          "stopDate": "2015-08-31",
          "sendHour": "15",
          "sendMinute": "30",
          "frequency": "WEEKLY",
          "interval": 1,
          "sendDays":["MO","TU", "WE", "TH", "FR"],
          "timeZone": "US/Pacific"
      },
      "templateId": "54b58250e4b0ec83add2661e",
      "stream": {
        "catgoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
        "description" : "Description 01",
        "emailPostingEnabled": false,
        "followersCount": 0,
        "id": "546e17fcd4c67da2547f5b61",
        "itemsCount": 0,
        "openForPosting": false,
        "openForReading": true,
        "ownerId": "55414a36e4b0436b6280e668",
        "published": true,
        "rssEnabled": false,
        "source": {
            "uri": "http://slashdot.org/rss"
        },
        "streamEmailAddress": "test.stream.01@email.attensa.net",
        "tagIds": ["54da78488ab02386a4658eee"],
        "title": "Test Stream 01",
        "type": "RSS",
        "_links": {
          "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
          "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
        }
      }
    }
  ]
}

This endpoint retrives a list of briefings that a user is subscribed to

Request

GET https://api.attensa.net/groups/{groupId}/briefings

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of briefings in each page	No	Integer	20

Response

Status code 200

See the paging metadata specification for more information on the _paging property

POST /groups

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "creatorId": "56161che546097aa51621b47"
       "description": "just a test group",
       "name": "test"
     }' \
     https://api.attensa.net/groups

Status code 201 with response as follows:

{
  "creatorId": "56161che546097aa51621b47",
  "description": "just a test group",
  "id": "55161cf7e4b097aa51621b47",
  "name": "test",
  "streamCount": 0,
  "userCount": 0,
  "_links": {
    "self": "http://localhost/groups/55161cf7e4b097aa51621b47"
  }
}

Create a new group.

Request

POST https://api.attensa.net/groups

JSON request body

Parameter	Description	Required	Format	Default
autoAddNewUsers	Flag to track whether new users should be added to group	No	boolean	false
creatorId	Id of the user that should be marked as creator	Yes	String	n/a
description	Description of the group	Yes	String	n/a
name	Name of the group	Yes	String	n/a

Response

Status code 201

When autoAddNewUsers is set to true, new users will not be added to the group when users are created via POST /users. The groups that have autoAddNewUsers set will need to be retrieved via GET /groups?autoAddNewUsers=true and new users will need to be added to each group via POST /groups/{groupId}/users.

POST /groups/{groupId}/users

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "id": "56161che546097aa51621b47"
     }' \
     https://api.attensa.net/groups/users

Status code 204 with empty body

Add a user to a group

Request

POST https://api.attensa.net/groups/users

JSON request body

Parameter	Description	Required	Format	Default
id	Id of the user that should be added to the group	Yes	String	n/a

Response

Status code 201

POST /groups/{groupId}/streams

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "streamId": "559bf709e4b008a9a53293c3"
     }' \
     https://api.attensa.net/groups/{groupId}/streams

Status code 204 with empty body

Set a group to follow a stream

Request

POST https://api.attensa.net/groups/{groupId}/streams

JSON request body

Parameter	Description	Required	Format	Default
streamId	Id of the stream to follow	Yes	String	n/a

Response

Status code 204

PUT /groups/{groupId}

curl -u username:password \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "creatorId": "56161che546097aa51621b47"
       "description": "just a test group",
       "name": "test",
       "autoAddNewUsers": true
     }' \
     https://api.attensa.net/groups/{groupId}

Status code 200 with response as follows:

{
  "creatorId": "56161che546097aa51621b47",
  "description": "just a test group",
  "id": "55161cf7e4b097aa51621b47",
  "name": "test",
  "streamCount": 0,
  "userCount": 0,
  "autoAddNewUsers": true
  "_links": {
    "self": "http://localhost/groups/55161cf7e4b097aa51621b47"
  }
}

Update an existing group. Updates are applied in a incremental PATCH-like manner, so the entire group resource does not need to be supplied, only the properties that are changing.

Request

PUT https://api.attensa.net/groups

JSON request body

Parameter	Description	Required	Format	Default
autoAddNewUsers	Flag to track whether new users should be added to group	No	boolean	false
creatorId	Id of the user that should be marked as creator	No	String	n/a
description	Description of the group	No	String	n/a
name	Name of the group	No	String	n/a

Response

Status code 200

DELETE /groups/{groupId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/groups/{groupId}

204 empty body returned on success

Delete an existing group from the system. All users will be un-followed and un-subscribed from streams they followed or subscribed to via this group.

Request

DELETE https://api.attensa.net/groups/{groupId}

Response

Status code 204 with empty body

DELETE /groups/{groupId}/users/{userId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/groups/{groupId}/users/{userId}

204 empty body returned on success

Remove a user from a group.

Request

DELETE https://api.attensa.net/groups/{groupId}/users/{userId}

Response

Status code 204 with empty body

DELETE /groups/{groupId}/streams/{streamId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/groups/{groupId}/streams/{streamId}

204 empty body returned on success

Unfollow a group from a stream.

Request

DELETE https://api.attensa.net/groups/{groupId}/streams/{streamId}

Response

Status code 204 with empty body.

Items

GET /items

curl -u username:password https://api.attensa.net/items

The above command returns JSON structured like this:

{
  "_paging": {
    "totalElementCount": 42,
    "pageCount": 3,
    "requestedPageSize": 20,
    "elementCount": 20,
    "page": 0
  },
  "items": [
    {
      "id": "5937ed4ce4b0dde7e4aee583",
      "title": "Lorem Ipsum",
      "shortDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut al",
      "link": "http://www.example.com/lorem/ipsum/2017/05/30",
      "created": "2017-05-30T14:39:18.936Z",
      "modified": "2017-05-30T14:39:18.936Z",
      "published": "2017-05-30T13:30:00.188Z",
      "streamId": "55773111e4b08d8c914d7d1a",
      "streamOriginId": "55773111e4b08d8c914d7d1a",
      "streamOriginTitle": "All the facts in Latin",
      "logoUrl": "https://example.com/set_by_streams/itemLogoUrl.png",
      "commentsCount": 0,
      "likesCount": 0,
      "readersCount": 0,
      "_links": {
        "self": "https://api.attensa.net/items/5937ed4ce4b0dde7e4aee583"
      }
    },
    ...
  ],
  "_links": {
      "first": "https://api.attensa.net/items?page=0",
      "last": "https://api.attensa.net/items?page=2",
      "next": "https://api.attensa.net/items?page=1"
  }
}

This endpoint retrieves a paged list of items.

Request

GET https://api.attensa.net/items

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of items in each page	No	Integer	20
sort	Field to sort the results on	No	attentionRank, created, modified or published	published
sortDirection	Sort ascending or descending	No	ASC or DESC	DESC
streamIds	Filter results to streamIds in list	No	comma separated ID list	`null`
userId	Annotate response with user specific info	No	`null`
includeComments	Field to request comments in response	No	boolean	false
includeReadItems	Field to request items read by user	No	boolean	true
includeFullDescription	Field to request full descriptions	No	boolean	false

Response

Status code 200

See the paging metadata specification for more information on the _paging property. See GET /items/{itemId} for an example of the comments json.

GET /items/{itemId}

curl -u username:password https://api.attensa.net/items/{itemId}

The above command returns JSON structured like this:

{
  "id": "5937ed4ce4b0dde7e4aee583",
  "title": "Lorem Ipsum",
  "shortDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut al",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
  "logoUrl": "https://example.com/set_by_streams/itemLogoUrl.png",
  "link": "http://www.example.com/lorem/ipsum/2017/05/30",
  "created": "2017-05-30T14:39:18.936Z",
  "modified": "2017-05-30T14:39:18.936Z",
  "published": "2017-05-30T13:30:00.188Z",
  "streamId": "55773111e4b08d8c914d7d1a",
  "streamOriginId": "55773111e4b08d8c914d7d1a",
  "streamOriginTitle": "All the facts in Latin",
  "commentsCount": 0,
  "likesCount": 0,
  "readersCount": 0,
  "comments": [
    {
      "id": "5a944d63e4b09d729edf2fd8",
       "body": "Text body of the comment",
       "created": "2018-01-26T18:09:39.207Z",
       "userId": "54177bb3e4d3fc6238a83bef",
       "userFullName": "Firstname Lastname"
    },
    {
      "id": "5a96c89ee4b075c1b10ac847",
      "body": "Testing adding a comment via customer api",
      "created": "2018-01-28T15:19:58.998Z",
      "userId": "5a173db3d3b0ff0238a83bee",
      "userFullName": "First Last"
    }
  ],
  "_links": {
    "self": "https://api.attensa.net/items/5937ed4ce4b0dde7e4aee583"
  }
}

This endpoint retrieves a specific item.

Request

GET https://api.attensa.net/items/{itemId}

Request query parameters

Parameter	Description	Required	Format	Default
userId	Annotate response with user specific info	No	`null`

Response

Status code 200

POST /items/{itemId}/comments

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "userId": "559bf709e4b008a9a53293c3",
       "body": "Comment text"
     }' \
     https://api.attensa.net/items/{itemId}/comments

The above command returns JSON structured like this:

{
    "id": "5a973318e4b00e62bf99334b",
    "body": "Comment text",
    "created": "2018-01-28T22:54:16.329Z",
    "userId": "559bf709e4b008a9a53293c3",
    "userFullName": "Firstname Lastname"
}

This endpoint creates a new user.

Request

POST https://api.attensa.net/items/{itemId}/comments

JSON request properties

Parameter	Description	Required	Format	Default
userId	Id of the liking user	Yes	String	n/a
body	Comment text	Yes	String	n/a

Response

Status code 201

POST /items/{itemId}/likes

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "userId": "559bf709e4b008a9a53293c3"
     }' \
     https://api.attensa.net/items/{itemId}/likes

Status code 204 with empty body

Set a user to like the item

Request

POST https://api.attensa.net/items/{itemId}/likes

JSON request body

Parameter	Description	Required	Format	Default
userId	Id of the liking user	Yes	String	n/a

Response

Status code 204

POST /items/{itemId}/readers

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "userId": "559bf709e4b008a9a53293c3"
     }' \
     https://api.attensa.net/items/{itemId}/readers

Status code 204 with empty body

Add a user to the item’s reader list

Request

POST https://api.attensa.net/items/{itemId}/readers

JSON request body

Parameter	Description	Required	Format	Default
userId	Id of reading user	Yes	String	n/a

Response

Status code 204 with empty body

DELETE /items/{itemId}/comments/{commentId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/items/{itemId}/comments/{commentId}

204 empty body returned on success

Remove comment from the item.

Request

DELETE https://api.attensa.net/items/{itemId}/comments/{commentId}

Response

Status code 204 with empty body

DELETE /items/{itemId}/likes/{userId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/items/{itemId}/likes/{userId}

204 empty body returned on success

Unset a user from liking the item.

Request

DELETE https://api.attensa.net/items/{itemId}/likes/{userId}

Response

Status code 204 with empty body

Streams

Stream Types

Attensa supports the following stream types

Type	Description	Can create	Can search
ATTENSA_SEARCH	Composed based on a search of items in other streams in Attensa	Yes	Yes
BING_SEARCH	Bing search results for either web or news search	Yes	Yes
CLINICALTRIALS_SEARCH	Content from clinicaltrials.gov	Yes	Yes
COLLECTION	A combination stream composed of items from other streams	Yes	Yes
FACTIVA_SELECT_HTTP	Content from a Factiva Select feed	No	Yes
PUBMED_SEARCH	Content from PubMed	Yes	Yes
RSS	Content from an RSS feed	Yes	Yes
TWITTER_SEARCH	Content based on a twitter search	Yes	Yes

GET /streams

curl -u username:password \
     -X GET \
     -d page=0 \
     -d published=true \
     -d rows=20 \
     -d term=test \
     -d type=COLLECTION \
     https://api.attensa.net/streams

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/streams?rows=20&page=0&term=test&type=COLLECTION&published=true",
    "last": "https://api.attensa.net/streams?rows=20&page=0&term=test&type=COLLECTION&published=true"
  },
  "streams": [{
    "id": "546e17fcd4c67da2547f5b61",
    "title": "Test Stream 01",
    "description": "Description 01",
    "ownerId": "55414a36e4b0436b6280e668",
    "type": "COLLECTION",
    "itemLogoUrl": "https://example.com/path_to_logo/which_will_also_update/items_logo_url.png"
    "emailPostingEnabled": true,
    "openForReading": true,
    "openForPosting": true,
    "published": true,
    "streamEmailAddress": "test.stream.01@email.attensa.net",
    "rssEnabled": false,
    "categoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
    "tagIds": ["54da78488ab02386a4658eee"],
    "substreams": [
      {
          "id": "559c1972e4b008b9a5329478",
          "title": "Hi, I am a substream!",
          "type": "RSS"
      }
    ],
    "_links": {
      "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
      "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
    }
  }]
}

Get a paged list of streams.

Request

GET https://api.attensa.net/streams

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
published	Filter stream list to published or unpublished streams. Omit for all streams.	No	Boolean	`null`
rows	Number of streams in each page	No	Integer	20
source.search	Term used for search based stream types (TWITTER_SEARCH, etc)	No	String	`null`
source.uri	Uri of RSS feed for RSS streams	No	String	`null`
term	A search term to narrow the list of streams returned	No	String	`null`
type	Filter results to a specific stream type	No	searchable stream type	`null`
tagIds	Filter results to streams with at least one of the tagIds	No	comma separated ID list	`null`
categoryIds	Filter results to streams with at least one of the categoryIds	No	comma separated ID list	`null`

Response

Status code 200

See the paging metadata specification for more information on the _paging property

GET /streams/{streamId}

curl -u username:password https://api.attensa.net/streams/{streamId}

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "title": "Test Stream 01",
  "ownerId": "55414a36e4b0436b6280e668",
  "description" : "Description 01",
  "type": "COLLECTION",
  "itemLogoUrl": "https://example.com/path_to_logo/to_use/to_initialize/items_logoUrl.png",
  "source": {
      "search": "search term",
      "uri": "http://slashdot.org/rss",
      "username": "myUserNameForSecuredRSSFeed"
  },
  "emailPostingEnabled": false,
  "openForReading": true,
  "openForPosting": true,
  "published": true,
  "streamEmailAddress": "test.stream.01@email.attensa.net",
  "rssEnabled": false,
  "catgoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
  "itemsCount": 0,
  "followersCount": 0,
  "tagIds": ["54da78488ab02386a4658eee"],
  "substreams": [
    {
        "id": "559c1972e4b008b9a5329478",
        "title": "Hi, I am a substream!",
        "type": "RSS"
    }
  ],
  "_links": {
    "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
    "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
  }
}

This endpoint retrieves a specific stream.

Request

GET https://api.attensa.net/streams/{streamId}

Response

Status code 200

GET /streams/{streamId}/items

curl -u username:password https://api.attensa.net/streams/{streamId}/items

Status code 200 with json structured as follows:

{
  "_links": {
    "first": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/items?page=0",
    "last": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/items?page=1",
    "next": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/items?page=1"
  },
  "_paging": {
    "elementCount": 20,
    "page": 0,
    "pageCount": 2,
    "requestedPageSize": 20,
    "totalElementCount": 34
  },
  "items": [
    {
      "id": "5421214ba4b0fd12d834a223",
      "title": "Lorem Ipsum",
      "shortDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas pulvinar blandit ante vel congue. Nulla et risus interdum, tristique sapien sit amet, suscipit diam. Vestibulum a sem sed lectus sagit",
      "link": "http://www.example.com/lorem/ipsum/2017/05/30",
      "created": "2017-05-30T14:39:18.936Z",
      "modified": "2017-05-30T14:39:18.936Z",
      "published": "2017-05-30T13:30:00.188Z",
      "streamId": "55773111e4b08d8c914d7d1a",
      "streamOriginId": "55773111e4b08d8c914d7d1a",
      "streamOriginTitle": "All the facts in Latin",
      "logoUrl": "https://example.com/initialized_based_on_value_of/stream_item_logo_url.png",
      "commentsCount": 0,
      "likesCount": 0,
      "readersCount": 0,
      "_links": {
        "self": "https://api.attensa.net/items/5421214ba4b0fd12d834a223"
      }
    }
  ]
}

Get items for a specific stream.

Request

GET https://api.attensa.net/streams/{streamId}/items

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
sort	Field to sort the results on	No	attentionaRank, created, modified or published	published
sortDirection	Sort ascending or descending	No	ASC or DESC	DESC
userId	Annotate response with user specific info	No	`null`
includeComments	Field to request comments in response	No	boolean	false
includeFullDescription	Field to request full descriptions	No	boolean	false

Response

Status code 200

See the paging metadata specification for more information on the _paging property. See GET /items/{itemId} for an example of the comments json.

GET /streams/{streamId}/users

curl -u username:password https://api.attensa.net/streams/{streamId}/users

Status code 200 with json structured as follows:

{
  "_links": {
    "first": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=0",
    "last": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=1",
    "next": "https://api.attensa.net/streams/55245b56e4b0db8a310d8767/users?page=1"
  },
  "_paging": {
    "elementCount": 20,
    "page": 0,
    "pageCount": 2,
    "requestedPageSize": 20,
    "totalElementCount": 34
  },
  "users": [
    {
      "_links": {
        "self": "https://api.attensa.net/users/5421903ae4b0fd12d843a219"
      },
      "emailAddress": "test@attensa.com",
      "firstName": "Adam",
      "id": "5421903ae4b0fd12d843a219",
      "lastName": "Test",
      "middleName": "J",
      "status": "ACTIVE",
      "suffix": "SR",
      "timeZone": "US/Pacific",
      "userIsFollowing": false
    }
  ]
}

Get users that are following a specific stream.

Request

GET https://api.attensa.net/streams/{streamId}/users

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of users returned	No	String	`null`
sort	Field to sort the results on	No	firstName, lastName or emailAddress	emailAddress
sortDirection	Sort ascending or descending	No	ASC or DESC	ASC

Response

Status code 200

POST /streams

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "title": "Test Stream 01",
       "description": "Description 01",
       "itemLogoUrl": "https://example.com/path_to_logo/to_use/to_initialize/items_logoUrl.png",
       "ownerId": "55414a36e4b0436b6280e668",
       "type": "RSS",
       "source": {
           "uri": "http://slashdot.org/rss",
           "username": "myUserNameForSecuredRSSFeed",
           "password": "myPasswordForSecuredRSSFeed"
       },
       "emailPostingEnabled": false,
       "openForReading": true,
       "rssEnabled": false,
       "tagIds": ["54da78488ab02386a4658eee"],
       "categoryIds" : ["55414a36e4b0436b6280e668"]
     }' \
     https://api.attensa.net/streams

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "title": "Test Stream 01",
  "ownerId": "55414a36e4b0436b6280e668",
  "description" : "Description 01",
  "itemLogoUrl": "https://example.com/path_to_logo/to_use/to_initialize/items_logoUrl.png",
  "type": "RSS",
  "source": {
      "uri": "http://slashdot.org/rss",
      "username": "myUserNameForSecuredRSSFeed"
  },
  "emailPostingEnabled": false,
  "streamEmailAddress": "test.stream.01@email.attensa.net",
  "openForReading": true,
  "openForPosting": true,
  "published": true,
  "rssEnabled": false,
  "catgoryIds" : ["55414a36e4b0436b6280e668"],
  "tagIds": ["54da78488ab02386a4658eee"],
  "itemsCount": 0,
  "followersCount": 0,
  "_links": {
    "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
    "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
  }
}

Create a new stream

Request

POST https://api.attensa.net/streams

JSON request properties

Parameter	Description	Required	Format	Default
title	Stream Title	Yes	String	n/a
description	Stream description	No	String	`null`
ownerId	User id of stream owner	Yes	String of valid user id	n/a
type	Stream type	Yes	creatable stream type	n/a
itemLogoUrl	Value used to initialize item.logoUrl	No	String	`null`
source:search	Search term. Only supply for ATTENSA_SEARCH, PUBMED_SEARCH or TWITTER_SEARCH streams	For type ATTENSA_SEARCH, PUBMED_SEARCH, TWITTER_SEARCH	String	`null`
source:uri	Uri of rss feed. Only supply for type RSS streams	For type RSS	String	`null`
source:type	Specify web or news search for BING_SEARCH streams	For type BING_SEARCH	`WEB` or `NEWS`	n/a
source:username	Basic auth username for secured rss feed. Only supply for type RSS streams.	For secured RSS streams	String	`null`
source:password	Basic auth password for secured rss feed. Only supply for type RSS streams.	For secured RSS streams	String	`null`
emailPostingEnabled	Allow posting to COLLECTION stream via email.	No	Boolean	false
streamEmailAddress	Email address to for stream if emailPosting is enabled. Only set for collection streams	No	Valid email string	`null`
openForReading	Allow all users to read this stream	No	boolean	false
openForPosting	Allow all users to post content to a COLLECTION stream	No	boolean	false
published	Publish the stream for users in your account to discover	No	boolean	false
rssEnabled	Allow public access to an RSS feed of this stream	No	boolean	false
tagIds	Stream tag IDs to tag the stream	No	[String]	[]
categoryIds	Categories to put the stream in	Yes (empty array for no categories)	[String]	[]

Response

Status code 201

POST /streams/{streamId}/streams

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "streamId": "5519ae56e4b0c0419a88bae1"
     }' \
     https://api.attensa.net/streams/{streamId}/streams

303 redirect returned pointing to parent stream resource

Add a substream to a COLLECTION stream.

Request

POST https://api.attensa.net/streams/{streamId}/streams

JSON request body parameters

Parameter	Description	Required	Format	Default
streamId	The streamId of the child stream to be added	Yes	String	n/a

Response

Status code 303 with Location header set to the url of the parent COLLECTION stream

POST /streams/{streamId}/items

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "author": "John Doe",
       "description": "Description 01",
       "sourceUrl": "http://google.com",
       "title": "Test item 01"
     }' \
     https://api.attensa.net/streams/{streamId}/items

Status code 202 with response as follows:

"Item successfully queued"

Post an item to a COLLECTION stream.

Request

POST https://api.attensa.net/streams/{streamId}/items

JSON request body parameters

Parameter	Description	Required	Format	Default
author	The author name of the item	No	String	`null`
description	The body of the item.	Yes	String	n/a
sourceUrl	Url of the item to link to	No	String	`null`
title	Item title	Yes	String	n/a

Response

Status code 202

POST /streams/{streamId}/items/{itemId}/attachments

curl -u username:password \
     -H "Content-Type: multipart/form-data" \
     -X POST \
     -F "attachment=@<path_to_target_file>" \
     https://api.attensa.net/streams/{streamId}/items/{itemId}/attachments

Status code 200 with response as follows:

{"result":"Attachment successfully added to Item."}

Add a file to an item as an attachment.

Request

POST https://api.attensa.net/streams/{streamId}/items/{itemId}/attachments

Response

Status code 200

PUT /streams/{streamId}

curl -u username:password \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "title": "Test Stream 01",
       "description": "Description 01",
       "itemLogoUrl": "https://example.com/path_to_logo/to_use/to_initialize/items_logoUrl.png",
       "ownerId": "55414a36e4b0436b6280e668",
       "source": {
           "uri": "http://slashdot.org/rss",
           "username": "myUserNameForSecuredRSSFeed",
           "password": "myPasswordForSecuredRSSFeed"
       },
       "emailPostingEnabled": false,
       "streamEmailAddress": "test.stream.01@email.attensa.net",
       "openForReading": true,
       "rssEnabled": false,
       "tagIds": ["54da78488ab02386a4658eee"],
       "categoryIds" : ["55414a36e4b0436b6280e668"]
     }' \
     https://api.attensa.net/streams/{streamId}

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "title": "Test Stream 01",
  "ownerId": "55414a36e4b0436b6280e668",
  "description" : "Description 01",
  "itemLogoUrl": "https://example.com/path_to_logo/to_use/to_initialize/items_logoUrl.png",
  "type": "RSS",
  "source": {
      "uri": "http://slashdot.org/rss",
      "username": "myUserNameForSecuredRSSFeed"
  },
  "tagIds": ["54da78488ab02386a4658eee"],
  "emailPostingEnabled": false,
  "openForReading": true,
  "openForPosting": true,
  "published": true,
  "rssEnabled": false,
  "catgoryIds" : ["55414a36e4b0436b6280e668"],
  "itemsCount": 0,
  "followersCount": 0,
  "_links": {
    "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
    "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
  }
}

Update an existing stream. Updates are applied in a incremental PATCH-like manner, so the entire stream resource does not need to be supplied, only the properties that are changing.

Request

PUT https://api.attensa.net/streams/{streamId}

JSON body request properties

Parameter	Description	Required	Format	Default
title	Stream Title	No	String	n/a
description	Stream description	No	String	n/a
itemLogoUrl	Value used to initialize item.logoUrl	No	String	`null`
ownerId	User id of stream owner	No	String of valid user id	n/a
source:search	Search term. Only supply for ATTENSA_SEARCH, PUBMED_SEARCH or TWITTER_SEARCH streams	No	String	n/a
source:uri	Uri of rss feed. Only supply for type RSS streams	No	String	n/a
source:username	Basic auth username for secured rss feed. Only supply for type RSS streams.	No	String	n/a
source:password	Basic auth password for secured rss feed. Only supply for type RSS streams.	No	String	n/a
emailPostingEnabled	Allow posting to COLLECTION stream via email.	No	Boolean	n/a
streamEmailAddress	Email address for stream if emailPosting is enabled. Only set for collection streams	No	Valid email string	n/a
openForReading	Allow all users to read this stream	No	Boolean	n/a
openForPosting	Allow all users to post content to a COLLECTION stream	No	Boolean	n/a
published	Publish the stream for users in your account to discover	No	boolean	false
rssEnabled	Allow public access to an RSS feed of this stream	No	Boolean	n/a
tagIds	Stream tag IDs to tag the stream	No	[String]	n/a
categoryIds	Categories to put the stream in	No	[String]	n/a

All categories or stream tags can be removed by sending an empty categoryIds or tagIds array ("categoryIds": [])

Response

Status code 200

DELETE /streams/{streamId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/streams/{streamId}

204 emtpy body returned on success

Delete an existing stream from the system. All users will be unfollowed from the stream when it is deleted.

Request

DELETE https://api.attensa.net/streams/{streamId}

Response

Status code 204 with empty body

Request

DELETE https://api.attensa.net/streams/{streamId}/streams/{substreamId}

Response

Status code 204 with empty body

DELETE /streams/{streamId}/streams/{substreamId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/streams/{streamId}/streams/{substreamId}

204 empty body returned on success

Remove a substream from an existing COLLECTION stream.

Request

DELETE https://api.attensa.net/streams/{streamId}/streams/{substreamId}

Response

Status code 204 with empty body

Stream Tags

GET /streamTags

curl -u username:password https://api.attensa.net/streamTags

Status code 200 with response as follows:

[
  {
    "id": "5547ad95d4c6285588f4b23c",
    "label": "Cheese"
  },
  {
    "id": "9090ad95d4c6285588f4b23c",
    "label": "Wiz"
  }
]

Get a list of all stream tags.

Request

GET https://api.attensa.net/streamTags

Response

Status code 200

GET /streamTags/{tagId}/streams

curl -u username:password \
     -X GET \
     -d page=0 \
     -d published=firstName
     -d rows=20 \
     -d term=test \
     -d type=COLLECTION
     https://api.attensa.net/streamTags/{tagId}/streams

Status code 200 with response as follows:

{
  "_paging": {
    "totalElementCount": 1,
    "pageCount": 1,
    "requestedPageSize": 20,
    "elementCount": 1,
    "page": 0
  },
  "_links": {
    "first": "https://api.attensa.net/streamTags/{tagId}/streams?rows=20&page=0&term=test&published=true&type=COLLECTION",
    "last": "https://api.attensa.net/streamTags/{tagId}/streams?rows=20&page=0&term=test&published=true&type=COLLECTION"
  },
  "streams": [{
    "title": "Test Stream 01",
    "groupIsSubscribed": true,
    "description": "Description 01",
    "ownerId": "55414a36e4b0436b6280e668",
    "type": "COLLECTION",
    "emailPostingEnabled": true,
    "openForReading": true,
    "openForPosting": true,
    "published": true,
    "streamEmailAddress": "test.stream.01@email.attensa.net",
    "substreams":[
      {
        "id": "559c1972e4b008b9a5329478",
        "title": "Hi, I am a substream!",
        "type": "RSS"
      }
    ],
    "rssEnabled": false,
    "categoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
    "tagIds": ["55414a36e9878136b6280e668"]
  }]
}

Retrieve a paged list of streams that are tagged with a certain stream tag.

Request

GET https://api.attensa.net/streamTags/{tagId}/streams

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
published	Filter stream list to published or unpublished streams. Omit for all streams.	No	Boolean	`null`
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of streams returned	No	String	`null`
type	Filter results to a specific stream type	No	searchable stream type	`null`

Response

Status code 201

See the paging metadata specification for more information on the _paging and _links properties

POST /streamTags

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "label": "Cheese"
     }' \
     https://api.attensa.net/streamTags

Status code 201 with response as follows:

{
  "id": "56161che546097aa51621b47",
  "label": "Cheese"
}

Create a new stream tag.

Request

POST https://api.attensa.net/streamTags

JSON request body

Parameter	Description	Required	Format	Default
label	The tag label	Yes	String	n/a

Response

Status code 201

PUT /streamTags/{tagId}

curl -u username:password \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "label": "Wiz"
     }' \
     https://api.attensa.net/streamTags/{tagId}

Status code 200 with response as follows:

{
  "id": "56161che546097aa51621b47",
  "label": "Wiz"
}

Edit the label of an existing stream tag

Request

PUT https://api.attensa.net/streamTags/{tagId}

JSON request body

Parameter	Description	Required	Format	Default
label	The tag label	Yes	String	n/a

Response

Status code 200

DELETE /streamTags/{tagId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/streamTags/{tagId}

204 empty body returned on success

Delete an existing stream tag from the system. All streams tagged with that tag will have that tag removed.

Request

DELETE https://api.attensa.net/streamTags/{tagId}

Response

Status code 204 with empty body

Reports

GET /reports

curl -u username:password https://api.attensa.net/reports

Status code 200 with response as follows:

[
  {
    "fromDate": "2016-05-04",
    "size": 123,
    "toDate": "2016-05-11",
    "type": "briefing_activity",
    "url": "<snip>"
  }
]

Get a list of all user activity reports for your account. The url property will contain a signed link that is valid for 15 minutes that points to a tab seperated file with user activity.

Request

GET https://api.attensa.net/reports

Response

Status code 200

Users

GET /users

curl -u username:password https://localhost:8000/users

The above command returns JSON structured like this:

{
  "_paging": {
    "totalElementCount": 42,
    "pageCount": 3,
    "requestedPageSize": 20,
    "elementCount": 20,
    "page": 0
  },
  "users": [
    {
      "id": "546e17fcd4c67da2547f5b61",
      "firstName": "test",
      "middleName": "j",
      "lastName": "user",
      "suffix": "sr",
      "emailAddress": "foo@test.com",
      "timeZone": "Europe/Paris",
      "status": "ACTIVE",
      "_links": {
        "self": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61"
      }
    }
  ]
}

This endpoint retrieves a paged list of users.

Request

GET https://api.attensa.net/users

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of users returned	No	String	`null`
sort	Field to sort the results on	No	firstName, lastName or emailAddress	emailAddress
sortDirection	Sort ascending or descending	No	ASC or DESC	ASC

Response

Status code 200

See the paging metadata specification for more information on the _paging property

GET /users/{userId}

curl -u username:password https://api.attensa.net/users/{userId}

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "firstName": "test",
  "middleName": "j",
  "lastName": "user",
  "suffix": "sr",
  "emailAddress": "foo@test.com",
  "timeZone": "Europe/Paris",
  "status": "ACTIVE",
  "_links": {
    "self": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61"
  }
}

This endpoint retrieves a specific user.

Request

GET https://api.attensa.net/users/{userId}

Response

Status code 200

GET /users/{userId}/items

curl -u username:password https://api.attensa.net/users/{userId}/items

Status code 200 with json structured as follows:

{
  "_links": {
    "first": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/items?page=0",
    "last": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/items?page=1",
    "next": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/items?page=1"
  },
  "_paging": {
    "elementCount": 20,
    "page": 0,
    "pageCount": 2,
    "requestedPageSize": 20,
    "totalElementCount": 34
  },
  "items": [
    {
      "id": "5421214ba4b0fd12d834a223",
      "title": "Lorem Ipsum",
      "shortDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas pulvinar blandit ante vel congue. Nulla et risus interdum, tristique sapien sit amet, suscipit diam. Vestibulum a sem sed lectus sagit",
      "link": "http://www.example.com/lorem/ipsum/2017/05/30",
      "created": "2017-05-30T14:39:18.936Z",
      "modified": "2017-05-30T14:39:18.936Z",
      "published": "2017-05-30T13:30:00.188Z",
      "streamId": "55773111e4b08d8c914d7d1a",
      "streamOriginId": "55773111e4b08d8c914d7d1a",
      "streamOriginTitle": "All the facts in Latin",
      "logoUrl": "https://example.com/set_by_streams/itemLogoUrl.png",
      "likedByUser": false,
      "readByUser": false,
      "savedByUser": true,
      "attentionRank": 0,
      "commentsCount": 0,
      "likesCount": 0,
      "readersCount": 0,
      "_links": {
        "self": "https://api.attensa.net/items/5421214ba4b0fd12d834a223"
      }
    }
  ]
}

Get items from the streams the user follows.

Request

GET https://api.attensa.net/users/{userId}/items

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
sort	Field to sort the results on	No	attentionRank, created, modified or published	published
sortDirection	Sort ascending or descending	No	ASC or DESC	DESC
includeComments	Field to request comments in response	No	boolean	false
includeFullDescription	Field to request full descriptions	No	boolean	false

Response

Status code 200

See the paging metadata specification for more information on the _paging property. See GET /items/{itemId} for an example of the comments json.

GET /users/{userId}/savedItems

curl -u username:password https://api.attensa.net/users/{userId}/items

Status code 200 with json structured as follows:

{
  "_links": {
    "first": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/savedItems?page=0",
    "last": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/savedItems?page=1",
    "next": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61/savedItems?page=1"
  },
  "_paging": {
    "elementCount": 20,
    "page": 0,
    "pageCount": 2,
    "requestedPageSize": 20,
    "totalElementCount": 34
  },
  "items": [
    {
      "id": "5421214ba4b0fd12d834a223",
      "title": "Lorem Ipsum",
      "shortDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas pulvinar blandit ante vel congue. Nulla et risus interdum, tristique sapien sit amet, suscipit diam. Vestibulum a sem sed lectus sagit",
      "link": "http://www.example.com/lorem/ipsum/2017/05/30",
      "created": "2017-05-30T14:39:18.936Z",
      "modified": "2017-05-30T14:39:18.936Z",
      "published": "2017-05-30T13:30:00.188Z",
      "streamId": "55773111e4b08d8c914d7d1a",
      "streamOriginId": "55773111e4b08d8c914d7d1a",
      "streamOriginTitle": "All the facts in Latin",
      "logoUrl": "https://example.com/set_by_streams/itemLogoUrl.png",
      "likedByUser": false,
      "readByUser": false,
      "savedByUser": true,
      "attentionRank": 0,
      "commentsCount": 0,
      "likesCount": 0,
      "readersCount": 0,
      "_links": {
        "self": "https://api.attensa.net/items/5421214ba4b0fd12d834a223"
      }
    }
  ]
}

Get saved items for the user.

Request

GET https://api.attensa.net/users/{userId}/savedItems

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
sort	Field to sort the results on	No	attentionRank, created, modified or published	published
sortDirection	Sort ascending or descending	No	ASC or DESC	DESC
includeComments	Field to request comments in response	No	boolean	false
includeFullDescription	Field to request full descriptions	No	boolean	false

Response

Status code 200

See the paging metadata specification for more information on the _paging property. See GET /items/{itemId} for an example of the comments json.

GET /users/{userId}/streams

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     -d term=test \
     https://api.attensa.net/users/{userId}/streams

The above command returns JSON structured like this:

{
  "_paging": {
    "elementCount": 1,
    "page": 0,
    "pageCount": 1,
    "requestedPageSize": 20,
    "totalElementCount": 1
  },
  "streams": [
    {
      "id": "546e17fcd4c67da2547f5b61",
      "title": "Test Stream 01",
      "ownerId": "55414a36e4b0436b6280e668",
      "description" : "Description 01",
      "type": "RSS",
      "source": {
          "uri": "http://slashdot.org/rss"
      },
      "emailPostingEnabled": false,
      "openForReading": true,
      "openForPosting": false,
      "published": true,
      "streamEmailAddress": "test.stream.01@email.attensa.net",
      "rssEnabled": false,
      "tagIds": ["54da78488ab02386a4658eee"],
      "catgoryIds" : ["55414a36e4b0436b6280e668", "823hg4asf34b0436b6280e668"],
      "itemsCount": 0,
      "followersCount": 0,
      "userIsFollowing": true,
      "_links": {
          "self": "https://api.attensa.net/streams/546e17fcd4c67da2547f5b61",
          "owner": "https://api.attensa.net/users/55414a36e4b0436b6280e668"
      }
    }
  ]
}

This endpoint retrives a list of streams that a user is following.

Request

GET https://api.attensa.net/users/{userId}/streams

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20
term	A search term to narrow the list of streams returned	No	String	`null`
tagIds	Filter results to streams with at least one of the tagIds	No	comma separated ID list	`null`
categoryIds	Filter results to streams with at least one of the categoryIds	No	comma separated ID list	`null`

Response

Status code 200

See the paging metadata specification for more information on the _paging property.

GET /users/{userId}/briefings

curl -u username:password \
     -X GET \
     -d rows=20 \
     -d page=0 \
     https://api.attensa.net/users/{userId}/briefings

The above command returns JSON structured like this:

{
  "_paging": {
    "elementCount": 1,
    "page": 0,
    "pageCount": 1,
    "requestedPageSize": 20,
    "totalElementCount": 1
  },
  "_links": {
    "first": "https://api.attensa.net/users/{userId}/briefings?rows=20&page=0",
    "last": "https://api.attensa.net/users/{userId}/briefings?rows=20&page=0"
  },
  "briefings": [
    {
      "id": "546e17fcd4c88ef1547b4f33",
      "ownerId": "55414a36e4b0436b6280e668",
      "briefingTitle": "Daily Briefing Example",
      "templateTitle": "Title that can be used inside Templates via helpers",
      "description": "Daily news sent ever day.",
      "subject": "Your Daily News!",
      "templateId": "54eba226e4b050dd8b9c1099",
      "subscriberCount": 0,
      "schedule": {
        "frequency": "DAILY",
        "interval": 2,
        "sendHour": 10,
        "sendMinute": 30,
        "startDate": "2017-03-29",
        "timeZone": "US/Pacific"
      },
      "streamIds": [
        "55fae1c6e4b0efbbd6062867",
        "585206dbe4b06537eec79b04",
        "55e4e635e4b00de911f2259a"
      ]
    }
  ]
}

This endpoint retrives a list of briefings that a user is subscribed to

Request

GET https://api.attensa.net/users/{userId}/briefings

Request query parameters

Parameter	Description	Required	Format	Default
page	The page number to retrieve	No	Integer	0
rows	Number of users in each page	No	Integer	20

Response

Status code 200

See the paging metadata specification for more information on the _paging property

POST /users

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "firstName": "test",
       "middleName": "j",
       "lastName": "user",
       "suffix": "sr",
       "emailAddress": "foo@test.com",
       "timeZone": "Europe/Paris",
       "status": "ACTIVE"
     }' \
     https://api.attensa.net/users

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "firstName": "test",
  "middleName": "j",
  "lastName": "user",
  "suffix": "sr",
  "emailAddress": "foo@test.com",
  "timeZone": "Europe/Paris",
  "status": "ACTIVE",
  "_links": {
    "self": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61"
  }
}

This endpoint creates a new user.

Request

POST https://api.attensa.net/users

JSON request properties

Parameter	Description	Required	Format	Default
firstName	First name	Yes	String	n/a
middleName	Middle name	No	String	`null`
lastName	Last name	Yes	String	n/a
suffix	Suffix (e.g. JR, SR)	No	String	`null`
emailAddress	Email Address (unique)	Yes	String in valid email format	n/a
timeZone	Supported time zone	Supported time zone string	`null`
status	User’s status	Yes	ACTIVE, INVITED or INACTIVE	ACTIVE

Response

Status code 201

POST /users/{userId}/briefings

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "briefingId": "546e17fcd4c88ef1547b4f33"
     }' \
     https://api.attensa.net/users/{userId}/briefings

Have a user follow a stream and optionally subscribe to the streams briefing.

Request

POST https://api.attensa.net/users/{userId}/briefings

Request body parameters

Parameter	Description	Required	Format	Default
briefingId	The stream for the user to follow	Yes	String	n/a

Response

Status code 204 with empty body

POST /users/{userId}/savedItems

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "itemId": "559bf709e4b008a9a53293c3"
     }' \
     https://api.attensa.net/users/{userId}/savedItems

Status code 204 with empty body

Set a user to like the item

Request

POST https://api.attensa.net/users/{userId}/savedItems

JSON request body

Parameter	Description	Required	Format	Default
itemId	Id of item to save	Yes	String	n/a

Response

Status code 204

POST /users/{userId}/streams

curl -u username:password \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "streamId": "546e17fcd4c67da2547f5b61"
     }' \
     https://api.attensa.net/users/{userId}/streams

Have a user follow a stream.

Request

POST https://api.attensa.net/users/{userId}/streams

Request body parameters

Parameter	Description	Required	Format	Default
briefingId	The briefing for the user to subscribe to	Yes	String	n/a

Response

Status code 204 with empty body

PUT /users/{userId}

curl -u username:password \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "firstName": "test",
       "middleName": "j",
       "lastName": "user",
       "suffix": "sr",
       "emailAddress": "foo@test.com",
       "timeZone": "Europe/Paris",
       "status": "ACTIVE"
     }' \
     https://api.attensa.net/users/{userId}

The above command returns JSON structured like this:

{
  "id": "546e17fcd4c67da2547f5b61",
  "firstName": "test",
  "middleName": "j",
  "lastName": "user",
  "suffix": "sr",
  "emailAddress": "foo@test.com",
  "timeZone": "Europe/Paris",
  "status": "ACTIVE",
  "_links": {
    "self": "https://api.attensa.net/users/546e17fcd4c67da2547f5b61"
  }
}

This endpoint updates an existing user.

Request

PUT https://api.attensa.net/users/{userId}

JSON request properties

No fields are required, but at least one must be provided for update. Updates are applied incrementally in a PATCH-like manner, so omitted fields will not be changed.

Parameter	Description	Required	Format
firstName	First name	No	String
middleName	Middle name	No	String
lastName	Last name	No	String
suffix	Suffix (e.g. JR, SR)	No	String
emailAddress	Email Address (unique)	Yes	String in valid email format
timeZone	Supported time zone	Supported time zone string
status	User’s status	Yes	ACTIVE, INVITED or INACTIVE

Response

Status code 200

DELETE /user/{userId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/users/{userId}

204 empty body returned on success

This endpoint deletes an existing user

Request

DELETE https://api.attensa.net/users/{userId}

Response

Status code 204, empty body

DELETE /user/{userId}/briefings/{briefingId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/users/{userId}/briefings/{briefingId}

204 empty body returned on success

This endpoint unsubscribes a user from a briefing.

Request

DELETE https://api.attensa.net/users/{userId}/briefings/{briefingId}

Response

Status code 204, empty body

DELETE /user/{userId}/savedItems/{itemId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/users/{userId}/savedItems/{itemId}

204 empty body returned on success

This endpoint removes an item from a user’s saved item list.

Request

DELETE https://api.attensa.net/users/{userId}/savedItems/{itemId}

Response

Status code 204, empty body

DELETE /user/{userId}/streams/{streamId}

curl -u username:password \
     -X DELETE \
     https://api.attensa.net/users/{userId}/streams/{streamId}

204 empty body returned on success

This endpoint unfollows a user from a stream.

Request

DELETE https://api.attensa.net/users/{userId}/streams/{streamId}

Response

Status code 204, empty body

Paging

Paging format

Paged responses return _paging and _links elements

{
  "_paging": {
    "totalElementCount": 82,
    "pageCount": 5,
    "requestedPageSize": 20,
    "elementCount": 20,
    "page": 2
  },
  "_links": {
    "first": "https://api.attensa.net/users?rows=20&page=0",
    "last": "https://api.attensa.net/users?rows=20&page=4",
    "next": "https://api.attensa.net/users?rows=20&page=3",
    "previous": "https://api.attensa.net/users?rows=20&page=1"
  },
  "users": [
    { "arrayOfUsers": "goes here" }
  ]
}

Paged responses will return _paging and _links elements.

`_paging` metadata:

totalElementCount: The total number of elements across all pages
pageCount: The number of pages
requestedPageSize: The requested page size
elementCount: The number of elements returned in the current page. Not that in some cases this may be less than the requested page size due to de-duping rules or filters
page: The current page number

`_links` for paging:

first: The first page (page 0) of the current result set
last: The last page of the current result set
next: The page immediately after the current page. Omitted if the current page is last.
previous: The page before the current page. Omitted if the current page is first.

The return data will be named for the type of data being responded to (e.g. requesting users will return a users array while requesting streams will return a streams array)

Template Data

Briefing Variables

Briefing data helpers available to templates.

`items` > `item` :

These are all the items in the briefing, with standard item data, plus the following:

{{title}}: The title of the item.
{{link}}: A link to the content of the item in the Attensa reading view.
{{sourceLink}}: A link to the content’s original source.
{{linkResolverLink}}: Provides a link resolver link for the article if one exists.
{{author}}: The full name of the author of the item.
{{defaultDescription}}: The full text of the item description.
{{cleanDescription}}: The same text as defaultDescription with any HTML stripped off.
{{shortDescription}}: The same text as cleanDescription with a limitation to 200 characters.
{{publishedDate}}: The item’s published date.

`briefing` :

{{briefing.briefingTitle}}: The title text for the briefing.
{{briefing.commentary.title}}: The briefing’s commentary’s title.
{{briefing.commentary.body}}: The briefing’s commentary’s body.
{{briefing.description}}: The briefing’s description.
{{briefing.templateTitle}}: The title text for the briefing’s template.
{{viewAsHTML}}: A link to the HTML version of the briefing inside of Attensa.
{{totalNewItems}}: The count of items added since the last briefing was sent.
{{startDate}}: The start date and time of the briefing.
{{endDate}}: The end date and time of the briefing.
{{recipientUserId}}: The userId of the recipient of the briefing email.
{{hostName}}: The hostName of the tenancy sending the briefing.
{{indexedStreams}}: The first level of non-empty streams in a briefing, with the following:
{{streamId}}: The indexed stream’s Id.
{{streamTitle}}: The indexed stream’s title.
{{streamDescription}}: The indexed stream’s description.
{{itemsCount}}: Count of items in the indexed stream.
{{items}}: All items in the indexed stream.

Time Zones

Supported time zones

For services that get or set a time zone, the following timezone strings are supported:

America/Argentina/Buenos_Aires
Asia/Almaty
Asia/Bangkok
Asia/Colombo
Asia/Hong_Kong
Asia/Kabul
Asia/Karachi
Asia/Kathmandu
Asia/Tokyo
Atlantic/Cape_Verde
Australia/Darwin
Brazil/DeNoronha
Canada/Atlantic
Canada/Newfoundland
Europe/Kaliningrad
Europe/London
Europe/Moscow
Europe/Paris
Europe/Samara
Pacific/Guam
Pacific/Majuro
Pacific/Noumea
US/Alaska
US/Central
US/Eastern
US/Hawaii
US/Mountain
US/Pacific
US/Samo

Introduction

Authentication

Briefings

GET /briefings

Request

Request query parameters

Response

GET /briefings/{briefingId}

Request

Response

GET /briefings/{briefingId}/preview

Request

Response

GET /briefings/{briefingId}/streams

Request

Request query parameters

Response

GET /briefings/{briefingId}/users

Request

Request query parameters

Response

POST /briefings

Request

JSON request properties

Response

PUT /briefings/{briefingId}

Request

JSON body request properties

Response

DELETE /briefings/{briefingId}

Request

Response

DELETE /briefings/{briefingId}/streams/{streamId}

Request

Response

DELETE /briefings/{briefingId}/users/{userId}

Request

Response

Categories

GET /categories

Request

Response

GET /categories/{categoryId}/streams

Request

Request query parameters

Response

GET /categories/uncategorized/streams

Request

Request query parameters

Response

PUT /categories

Request

JSON request body parameters

Groups

GET /groups

Request

Request query parameters

Response

GET /groups/{groupId}

Request

Response

GET /groups/{groupId}/users

Request

Request query parameters

Response

GET /groups/{groupId}/streams

Request

Request query parameters

Response

GET /groups/{groupId}/briefings

Request

Request query parameters

Response

POST /groups

Request

JSON request body

Response

POST /groups/{groupId}/users

Request

JSON request body