Post

A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph. If you want to create data that isn’t tied to the follow graph, you should look at Messages.

{
  "canonical_url": "https://alpha.app.net/adn/post/914440",
  "created_at": "2012-10-11T19:48:40Z",
  "entities": {
    "hashtags": [
      {
        "len": 8,
        "name": "adnhack",
        "pos": 90
      }
    ],
    "links": [
      {
        "len": 29,
        "pos": 100,
        "text": "http://appnet.eventbrite.com/",
        "url": "http://appnet.eventbrite.com/"
      }
    ],
    "mentions": [

    ]
  },
  "html": "<span itemscope=\"https://app.net/schemas/Post\">If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first <span data-hashtag-name=\"adnhack\" itemprop=\"hashtag\">#adnhack</span> => <a href=\"http://appnet.eventbrite.com/\">http://appnet.eventbrite.com/</a></span>",
  "id": "914440",
  "machine_only": false,
  "num_replies": 1,
  "num_reposts": 3,
  "num_stars": 3,
  "source": {
    "client_id": "caYWDBvjwt2e9HWMm6qyKS6KcATHUkzQ",
    "link": "https://alpha.app.net",
    "name": "Alpha"
  },
  "text": "If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first #adnhack => http://appnet.eventbrite.com/",
  "thread_id": "914440",
  "user": "...user object...",
  "you_reposted": false,
  "you_starred": false,
  "annotations": [
    {
      "type": "net.app.core.geolocation",
      "value": {
        "latitude": 74.0064,
        "longitude": 40.7142
      }
    }
  ],
  "reposters": [
    "...user objects..."
  ],
  "starred_by": [
    "...user objects..."
  ]
}

Post Fields

Field Type Description
id string Primary identifier for a post. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
user object This is an embedded version of the User object. Note: In certain cases (e.g., when a user account has been deleted), this key may be omitted.
created_at string The time at which the post was create in ISO 8601 format.
text string User supplied text of the post. All Unicode characters allowed. Maximum length 256 characters. The maximum length can be retrieved from the Configuration endpoint.
html string Server-generated annotated HTML rendering of post text.
source object
Field Type Description
name string Description of the API consumer that created this post.
link string Link provided by the API consumer that created this post.
client_id string The public client_id of the API consumer that created this post.
reply_to string The id of the post this post is replying to (or null if not a reply).
canonical_url string The URL of the post's detail page on Alpha.
thread_id string The id of the post at the root of the thread that this post is a part of. If thread_id==id than this property does not guarantee that the thread has > 1 post. Please see num_replies.
num_replies integer The number of posts created in reply to this post.
num_stars integer The number of users who have starred this post.
num_reposts integer The number of users who have reposted this post.
annotations list Metadata about the entire post. See the Annotations documentation.
entities object Rich text information for this post. See the Entities documentation.
is_deleted boolean Has this post been deleted? For non-deleted posts, this key may be omitted instead of being false. If a post has been deleted, the text, html, and entities properties will be empty and may be omitted.
machine_only boolean Is this Post meant for humans or other apps? See Machine only Posts for more information.
you_starred boolean Have you starred this Post? May be omitted if this is not an authenticated request.
starred_by list A partial list of users who have starred this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if include_starred_by=1 is passed to App.net. May be omitted if this is not an authenticated request.
you_reposted boolean Have you reposted this Post? May be omitted if this is not an authenticated request.
reposters list A partial list of users who have reposted this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if include_reposters=1 is passed to App.net. May be omitted if this is not an authenticated request.
repost_of Post object If this post is a repost, this key will contain the complete original Post.

Deprecations

  • deleted has been deprecated and replaced with is_deleted. This key should not be used and will be removed from the Post object soon.

Post Annotations

Post annotations are immutable attributes that describe the entire post. Please see the Annotations documentation for more information.

Machine only Posts

Some posts with annotations data may not be meant for direct consumption by a User. For example, a chess app may create Posts with annotations representing chess moves but having human readable text doesn’t make sense. Machine only Posts solve this problem by allowing clients to create posts with annotations and without text. These posts must be specifically asked for by using the include_machine=1 query string parameter. They must contain at least one annotation and cannot contain any text. When deciding if a Post should be machine only, ask yourself “Would this Post make sense to a human?”

General parameters

Where noted, Post endpoints respond to the following query string parameters:

Name Required? Type Description
include_muted Optional integer (0 or 1) Should Posts from muted users be included? Defaults to false except when you specifically request a Post from a muted user or when you specifically request a muted user's stream.
include_deleted Optional integer (0 or 1) Should deleted Posts be included? Defaults to true.
include_directed_posts Optional integer (0 or 1) Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else.
include_machine Optional integer (0 or 1) Should machine only Posts be included? Defaults to false.
include_starred_by Optional integer (0 or 1) Should a sample of Users who have starred a Post be returned with the Post objects? Please see the Post schema. Defaults to false.
include_reposters Optional integer (0 or 1) Should a sample of Users who have reposted a Post be returned with the Post objects? Please see the Post schema. Defaults to false.
include_annotations Optional integer (0 or 1) Should annotations be included in the response objects? Defaults to false.
include_post_annotations Optional integer (0 or 1) Should Post annotations be included in the response objects? Defaults to false.
include_user_annotations Optional integer (0 or 1) Should User annotations be included in the response objects? Defaults to false.
include_html Optional integer (0 or 1) Should the html field be included alongside the text field in the response objects? Defaults to true.

Where noted, endpoints that return a stream of Posts additionally respond to pagination parameters.

Stream Faceting parameters

Stream Faceting allows you to filter and query a user’s personalized stream or unified stream with an interface similar to our Post Search API. If you use stream faceting, the API will only return recent posts in a user’s stream.

Currently the following stream facets are supported:

Name Required? Type Description
has_oembed_photo Optional integer (0 or 1) Only include posts with photo oembed annotations.

Sorting Posts

Post id is the ordering field for multiple posts, not created_at. created_at is meant to be displayed to users, not to sort Posts. This also makes pagination with since_id and before_id more straightforward. Posts are presently always returned in reverse chronological order (newest to oldest). As a result, the Posts endpoints will always return the newest posts that meet the requested criteria (e.g. before_id and count).

Description Method Path Token
Create a Post POST /posts User
Retrieve a Post GET /posts/{post_id} None
Delete a Post DELETE /posts/{post_id} User
Repost a Post POST /posts/{post_id}/repost User
Unrepost a Post DELETE /posts/{post_id}/repost User
Star a Post POST /posts/{post_id}/star User
Unstar a Post DELETE /posts/{post_id}/star User
Retrieve multiple Posts GET /posts Any
Retrieve a User's posts GET /users/{user_id}/posts None
Retrieve a User's starred posts GET /users/{user_id}/stars None
Retrieve Posts mentioning a User GET /users/{user_id}/mentions Any
Retrieve Posts containing a hashtag GET /posts/tag/{hashtag} None
Retrieve replies to a Post GET /posts/{post_id}/replies Any
Retrieve a User's personalized stream GET /posts/stream User
Retrieve a User's unified stream GET /posts/stream/unified User
Retrieve the Global stream GET /posts/stream/global None
Report a Post POST /posts/{post_id}/report User
Search for Posts GET /posts/search Any