Stream Marker

Stream markers provide a way to save a user's spot in a stream of posts or messages; a lightweight way to sync between clients, or pick up where you left off without otherwise saving it.

These are special pagination values for since_id and before_id that you must use on markable streams to actually read from its marker:

  • last_read: the current last_read_id of the stream's marker
  • last_read_inclusive
  • marker: the current id of the stream's marker
  • marker_inclusive

Current markable streams/names:

On creation of posts and messages, you can automatically update the "personal" and "channel" markers to the created ID by including update_marker=1 in the query string.

Endpoints:

POST /markers

Token: user

Scope: any

Post a list of marker objects. You may update up to 10 at once. id and name are required. You may include percentage for more accuracy.

id indicates the current position of the marker. last_read_id indicates the last item in the stream that has ever been consumed by the marker. To move that in reverse, you must include the query parameter reset_read_id=1.

For a channel to be marked "read", the marker id must be at or greater than the current most-recent message in it.

Example Call
curl "https://api.pnut.io/v0/markers" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "X-Pretty-Json: 1" \
    -H "Content-Type: application/json" \
    -d "[
  {
    \"name\": \"channel:12\",
    \"id\": \"2593\"
  }
]"
    -X POST`

Returns a list of the updated markers

{
    "meta": {
        "code": 200
    },
    "data": [
        {
            "id": "0",
            "last_read_id": "0",
            "percentage": 0,
            "updated_at": "ISO-8601",
            "version": "String",
            "name": "String"
        }
    ]
}