Skip to content

Latest commit

 

History

History
1101 lines (987 loc) · 34.8 KB

posts.md

File metadata and controls

1101 lines (987 loc) · 34.8 KB

Posts

Posts are currently the best implemented objects on the system. If you're looking to play around with part of the API, start here.

General parameters

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)

Deprecating min_id and max_id

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.

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.

Create a Post

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.

Required Scopes

  • write_post

URL

https://alpha-api.app.net/stream/0/posts

Data

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

Example

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,
    }
}

JSON Example

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,
    }
}

Retrieve a Post

Returns a specific Post.

This endpoint is currently migrated by the response_envelope migration. Please refer to the Migrations documentation for more info.

URL

https://alpha-api.app.net/stream/0/posts/[post_id]

Parameters

Name Required? Type Description
post_id Required string The post id

Example

GET https://alpha-api.app.net/stream/0/posts/1

{
    "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

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.

URL

https://alpha-api.app.net/stream/0/posts/[post_id]

Data

Name Required? Type Description
post_id Required string The post id

Example

DELETE https://alpha-api.app.net/stream/0/posts/1

{
    "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 the replies to a Post

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.

URL

https://alpha-api.app.net/stream/0/posts/[post_id]/replies

Parameters

Name Required? Type Description
post_id Required string The post id

See General Parameters for optional parameters you can use with this query.

Example

GET https://alpha-api.app.net/stream/0/posts/1/replies

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

Retrieve Posts created by a User

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.

URL

https://alpha-api.app.net/stream/0/users/[user_id]/posts

Parameters

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.

Example

GET https://alpha-api.app.net/stream/0/users/1/posts

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

Star a Post

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.

URL

https://api.app.net/stream/0/posts/[post_id]/star

Data

Name Required? Type Description
post_id Required string The post id

Example

POST https://api.app.net/stream/0/posts/1/star

{
    "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,
    }
}

Unstar a Post

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.

URL

https://api.app.net/stream/0/posts/[post_id]/star

Data

Name Required? Type Description
post_id Required string The post id

Example

DELETE https://api.app.net/stream/0/posts/1/star

{
    "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 Posts starred by a User

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.

URL

https://api.app.net/stream/0/users/[user_id]/stars

Parameters

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.

Example

GET https://api.app.net/stream/0/users/1/stars

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

Retrieve Posts mentioning a User

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.

URL

https://alpha-api.app.net/stream/0/users/[user_id]/mentions

Parameters

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.

Example

GET https://alpha-api.app.net/stream/0/users/2/mentions

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

Retrieve a User's personalized stream

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.

URL

https://alpha-api.app.net/stream/0/posts/stream

Parameters

See General Parameters for optional parameters you can use with this query.

Example

GET https://alpha-api.app.net/stream/0/posts/stream

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

Retrieve the Global stream

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.

URL

https://alpha-api.app.net/stream/0/posts/stream/global

Parameters

See General Parameters for optional parameters you can use with this query.

Example

GET https://alpha-api.app.net/stream/0/posts/stream/global

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

Retrieve tagged Posts

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.

URL

https://alpha-api.app.net/stream/0/posts/tag/[hashtag]

Parameters

See General Parameters for optional parameters you can use with this query.

Example

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