Posts are currently the best implemented objects on the system. If you're looking to play around with part of the API, start here.
Requests for streams of Posts can be filtered by passing query string parameters along with the request.
Name | Required? | Type | Description |
---|---|---|---|
min_id (Deprecating) |
Optional | string | The minimum Post id to return (the response *will include* this post id if it is valid). |
max_id (Deprecating) |
Optional | string | The maximum Post id to return (the response *will include* this post id if it is valid) |
since_id |
Optional | string | Include posts with post ids greater than this id. The response will not include this post id. |
before_id |
Optional | string | Include posts with post ids smaller than this id. The response will not include this post id. |
count |
Optional | integer | The number of Posts to return, up to a maximum of 200. Sorry, negative counts are temporarily disabled. |
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 starts with 1 or more @mentions. Defaults to false for "My Stream" and true everywhere else. |
include_annotations |
Optional | integer (0 or 1) | Should the post annotations be included in the Post? (Default: False ) |
include_machine |
Optional | integer (0 or 1) | Should machine only posts be included? (Default: False ) |
include_user (Coming soon) |
Optional | integer (0 or 1) | Should the nested User object be included in the Post? (Default depends upon the endpoint) |
After thinking through the pagination use cases more, we don't think min_id
and max_id
are the most useful parameters. We're planning on deprecating them in favor of since_id
and before_id
. If you have a use case that would benefit from inclusive parameters (min_id
and max_id
), please let us know.
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.
Create a new Post object. Mentions and hashtags will be parsed out of the post text, as will bare URLs.
You can also create a Post by sending JSON in the HTTP post body that matches the post schema with an HTTP header of Content-Type: application/json
. Currently, the only keys we use from your JSON will be text
, reply_to
, machine_only
and annotations
. To create complex posts, you must use the JSON interface. See the JSON example below.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
write_post
Name | Required? | Type | Description |
---|---|---|---|
text |
Required | string | The raw text of the post |
reply_to |
Optional | string | The id of the post that this new post is replying to |
POST https://alpha-api.app.net/stream/0/posts
DATA text=%40berg+FIRST+post+on+this+new+site+%23newsocialnetwork
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on this new site <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 0,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": []
},
"you_starred": false
},
"meta": {
"code": 200,
}
}
POST https://alpha-api.app.net/stream/0/posts?include_annotations=1 Content-Type: application/json DATA '{"text": "@berg FIRST post on this new site #newsocialnetwork", "annotations": [{"type": "net.app.core.geo", "value": {"type": "Point", "coordinates": [102.0, 0.5]}}]}'
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on this new site <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 0,
"num_stars": 0,
"annotations": [
{
"type": "net.app.core.geo",
"value": {
"type": "Point",
"coordinates": [102.0, .5]
}
}
],
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": []
},
"you_starred": false
},
"meta": {
"code": 200,
}
}
Returns a specific Post.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
post_id |
Required | string | The post id |
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
"meta": {
"code": 200,
}
}
Delete a Post. The current user must be the same user who created the Post. It returns the deleted Post on success.
Remember, access tokens can not be passed in a HTTP body for DELETE
requests. Please refer to the authentication documentation.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
post_id |
Required | string | The post id |
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
"meta": {
"code": 200,
}
}
Retrieve all the Posts that are in the same thread as this post. The specified Post does not have to be the root of the conversation. Additionally, the specified Post will be included in the response at the appropriate place.
This endpoint would be more accurately named stream/0/posts/[post_id]/thread
and may be renamed in a later API version.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
post_id |
Required | string | The post id |
See General Parameters for optional parameters you can use with this query.
{
"data": [
{
"id": "2", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@mthurman stop trolling",
"html": "<span itemprop=\"mention\" data-mention-name=\"mthurman\" data-mention-id=\"1\">@mthurman</span> stop trolling",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": "1",
"thread_id": "1",
"num_replies": 0,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "mthurman",
"id": "2",
"pos": 0,
"len": 9
}],
"hashtags": [{],
"links": []
},
"you_starred": false
},
...
],
"meta": {
"code": 200,
"max_id": "2",
"min_id": "1",
"more": false
}
}
Get the most recent Posts created by a specific User in reverse post order.
Note: the User object is not returned for these Posts.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
user_id |
Required | string | The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id . |
See General Parameters for optional parameters you can use with this query.
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
],
"meta": {
"code": 200,
"max_id": "47",
"min_id": "1"
"more": true
}
}
Save a given Post to the current User's stars. This is just a "save" action, not a sharing action. A User's stars are visible to others, but they are not automatically added to your followers' streams.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
post_id |
Required | string | The post id |
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 1,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": true
},
"meta": {
"code": 200,
}
}
Remove a Star from a Post.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
post_id |
Required | string | The post id |
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
"meta": {
"code": 200,
}
}
Get the most recent Posts starred by a specific User in reverse post order. Stars are a way for Users to save posts without rebroadcasting the Post to their followers.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
user_id |
Required | string | The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id . |
See General Parameters for optional parameters you can use with this query.
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 1,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": true
},
],
"meta": {
"code": 200,
"max_id": "47",
"min_id": "1"
"more": true
}
}
Get the most recent Posts mentioning by a specific User in reverse post order.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
Name | Required? | Type | Description |
---|---|---|---|
user_id |
Required | string | The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id . |
See General Parameters for optional parameters you can use with this query.
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
],
"meta": {
"code": 200,
"max_id": "36",
"min_id": "1",
"more": false
}
}
Return the 20 most recent Posts from the current User and the Users they follow.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
See General Parameters for optional parameters you can use with this query.
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
],
"meta": {
"code": 200,
"max_id": "39",
"min_id": "1",
"more": true
}
}
Return the 20 most recent Posts from the Global stream.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
See General Parameters for optional parameters you can use with this query.
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
],
"meta": {
"code": 200,
"max_id": "33",
"min_id": "1",
"more": true
}
}
Return the 20 most recent Posts for a specific hashtag.
This endpoint is currently migrated by the
response_envelope
migration. Please refer to the Migrations documentation for more info.
See General Parameters for optional parameters you can use with this query.
GET https://alpha-api.app.net/stream/0/posts/tag/newsocialnetwork
{
"data": [
...
{
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_starred": false
},
],
"meta": {
"code": 200,
"max_id": "78",
"min_id": "1",
"more": false
}
}