Curate mention

PUT /accounts/{account_id}/alerts/{alert_id}/mentions/{mention_id}

Updates an existing mention. These update concern majorly classification of the mention: indicating the folder, tags, effective tone of the mention, etc... You cannot modify the content of a mention, or its source.

Parameters

  • account_id (string) - Id of the account
  • alert_id (number) - Id of the alert
  • mention_id (number) - Id of the mention

Page content

Minimal curl example

curl -ig 'https://api.mention.net/api/accounts/{account_id}/alerts/{alert_id}/mentions/{mention_id}' \
    -X PUT \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept-Version: 1.19' \
    -d '{"read":true}'

As you see in the curl example, there is no minimal requirement in the PUT request in terms of attributes sent. Therefore, you can modify only a single parameter if you wish to.

Available properties

Properties _ Definition Example
favorite Classify as favorite (admin only) true
trashed Throw to trash (admin only) false
read Mark as read true
tags add tags to the mention [{name: "interesting", id: 46212}]
folder Move to folder "archive"
tone Set the tone of the mention 1

Favorite

favorite

Boolean value indicating if the mention was set as favorite. Note that if a mention is marked as favorite, it is automatically set to read.

Trashed

trashed

Boolean value indicating if the mention has been put in trash.

Read

read

Boolean value indicating that a mention was read.

Tags

tags

List of tags attributed to the mention. It is an array of json object, with at least an attribute id that indicates the tag. A mention can only be associated with an existing tag. It means that you have to create a tag first.

Folder

folder

Indicates the folder where the mention has been put. For a list of folders, you can fetch the app/data, where there is a folder section.

Tone

tone

Tone value given to the mention (such as positive, negative or neutral). Note that this is the tone key which is used. For a list of tone keys, you can fetch the app/data, where there is a tones section.

Request example

  • Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Version: 1.19
  • Body
{
    "favorite": true,
    "trashed": false,
    "read": true,
    "tags": [{"id": 123}],
    "folder": "archive",
    "tone": 1,
}

Response example

If the request was successful, the response will return the full mention data, just as if you did a GET request on that mention.

  • Body
{
    "id": "527849933",
    "alert_id": 112233,
    "title": "NASA image shows 'starburst spider' pattern on Mars",
    "description": "USA TODAY NASA image shows 'starburst spider' pattern on Mars USA TODAY NASA's Mars Reconnaissance Orbiter captured a stunning image of a \"starburst\" pattern on Mars ' surface. The \u201cstarbursts\u201d can be seen each spring when Mars ' seasonal cap of carbon \u2026",
    "original_url": "http:\/\/www.usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "clickable_url": "https:\/\/web.mention.com\/api\/url?token=eyJ0eXAiOiJKV1QiLChbGciOiJIUzI1NiJ9.eyJ1cmwiOJodHRwOlwvXC93d3cudXNhdG9kYkuY29tXC9zdG9eVwvdGVjaFwvbmF0a9uLW5vd1wvMjAxNlwvMDFcLzE0XC9uYXNLWltYWdlLXNob3dzLXN0YJidXJzdC1zcGlZXItcGF0dGVyb1tYXJzXC83ODc4MTA3NFwvIiwiYWNjb3VudF9pZI6NDM4NDA0LCJhbGVydF9pZI6MTE2NTk5NSwic291cmNlXlkIjo0LCJtZW50a9uX2lkIjoiNzU2NzM5MjMzMIifQ.XH7WJlYkOYTDFysZELmouro__7QVoe5pT9c1qeZw",
    "displayable_url": "usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "unique_id": "http:\/\/www.usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "published_at": "2016-01-14T17:16:27.10090700+00:00",
    "created_at": "2016-01-18T16:05:44.0+00:00",
    "country": "US",
    "updated_at": "2016-01-18T16:05:45.0+00:00",
    "favorite": true,
    "folder": "archive",
    "folder_set_by_user": true,
    "read": true,
    "tone": 1,
    "source_type": "news",
    "source_name": "USA TODAY",
    "source_url": "http:\/\/www.usatoday.com\/",
    "language_code": "en",
    "tasks": [

    ],
    "logs": [

    ],
    "children": {
        "children": [
            { ... mention ... },
            { ... mention ... },
            { ... mention ... },
        ],
        "total": 42,
        "_links": {
            "more": {
                "href": "/api/accounts/THE_ACCOUNT_ID/alerts/112233/mentions/527849937/children?limit=20&before_date=2014-03-20T18:10:37.53829200+00:00",
                "params": {
                    "limit": 20,
                    "before_date": "2014-03-20T18:10:37.53829200+00:00"
                }
            }
        }
    },
    "picture_url": "\/\/t3.gstatic.com\/images?q=tbn:ANd9GcQlW3QxiNh2YxxacyF0gR636ViYH6YS_0ONIRj9pf4OhiRZ8hHHyCQqdOYVgMuToZ1Iixhy",
    "tags": [{"id":123}],
    "offsets": {
        "title": [
            0,
            0,
            4,
            4,
            47,
            47,
            4,
            4
        ],
        "description": [
            10,
            10,
            4,
            4,
            57,
            57,
            4,
            4,
            72,
            72,
            4,
            4,
            79,
            79,
            4,
            4,
            161,
            161,
            4,
            4,
            223,
            223,
            4,
            4
        ],
        "url": [

        ],
        "source_name": [

        ],
        "source_url": [

        ]
    },
    "permissions": {
        "favorite": true,
        "change_folder": true,
        "create_task": true
    },
    "author_influence": {
        "id": "3153793048",
        "alert_id": 112233,
        "kind": "web",
        "url": "http:\/\/www.usatoday.com",
        "name": "usatoday.com",
        "score": 83,
        "scored_id": "usatoday.com"
    },
    "metadata": {
        "twitter": {
            "id_str": "800747234652340224",
            "user": {
                "id_str": "188302352"
            }
        }
    }
}

Twitter Restrictions

For Twitter mentions, the following attributes are not provided: title, description, description_medium, description_short, source_name, source_url, picture_url.

It is still possible to obtain this metadata by using the Twitter API directly, see this guide for more information.

Note that these restrictions apply only to programmatic accesses to the API, so the attributes are still available in CSV or Excel exports, or in the application itself.

Facebook and Instagram Restrictions

For Facebook and Instagram mentions, the following attributes are not provided: title, description, description_medium, description_short, source_name, source_url, picture_url.

We still provide the id of the post on the social network, but cannot provide a sustainable alternative to fetch the posts details from Facebook or Instagram APIs.

Note that these restrictions apply only to programmatic accesses to the API, so the attributes are still available in CSV or Excel exports, or in the application itself.

Original url

original_url

This is the original url of the mention. It can be used for automated lookups.

Clickable url

clickable_url

This is the url that should be used in the context of user interaction, that is, if this is not looked up by a bot, but by a human.

Displayable url

displayable_url

This is the url that should be displayed to users.

Children

children

It indicates if the mention has other related mention, that is, some kind of "duplicate" content. For instance, if the mention is a tweet, children would gather all retweets. Return a maximum of 3 children mentions. You can fetch all mention children.

Offsets

offsets

It is a list of all occurrences of keywords inside the mention. It lists the mention attributes where if may have found such occurrences:

...
"offsets":{
    "title":[...],
    "description":[...],
    ...
},
...

Inside these attributes, it indicates the exact position of the keyword(s). This is for instance used by our web app in order to highlight the characters matching keywords.

In this list, each multiple of 4 corresponds to a single keyword:

  1. offset in characters
  2. offset in utf-16 code units
  3. length in characters
  4. length in utf-16 code units

Example: Assume that the single keyword of your alert is NASA.

...
"offsets":{
    "description": [5, 5, 4, 4, 12, 12, 4, 4],
    ...
},
...

In the above, you have the information that NASA was found twice in the mention description:

  • once from character 5 to character 9 (start: 5, length:4)
  • once from character 12 to character 16 (start: 12, length: 4)

You should use utf-16 code units values if your language does not handle surrogates properly (e.g. if it counts characters like 𝒜 as two characters).

Permissions

permissions

A list of permissions of the current user for that mention.

Author influence

author_influence

Information about author (origin) of the mention, and its influence. To know more about authors, check the author section.

Metadata

metadata

This attribute contains source-specific informations.

Right now, only Twitter mentions have this attribute, and it contains the following attributes:

  • twitter.id_str: The ID of the tweet
  • twitter.user.id_str: The ID of the tweet's author

See this guide for fetching the full original Tweet.