145 lines
2.9 KiB
Markdown
145 lines
2.9 KiB
Markdown
---
|
|
title: markers API methods
|
|
description: Save and restore your position in timelines.
|
|
menu:
|
|
docs:
|
|
weight: 30
|
|
name: markers
|
|
parent: methods-timelines
|
|
identifier: methods-markers
|
|
aliases: [
|
|
"/methods/markers",
|
|
"/api/methods/markers",
|
|
"/methods/timelines/markers",
|
|
]
|
|
---
|
|
|
|
<style>
|
|
#TableOfContents ul ul ul {display: none}
|
|
</style>
|
|
|
|
## Get saved timeline positions {#get}
|
|
|
|
```http
|
|
GET /api/v1/markers HTTP/1.1
|
|
```
|
|
|
|
**Returns:** Hash of timeline key and associated [Marker]({{< relref "entities/Marker" >}})\
|
|
**OAuth:** User token + `read:statuses`\
|
|
**Version history:**\
|
|
3.0.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Query parameters
|
|
|
|
timeline[]
|
|
: Array of String. Specify the timeline(s) for which markers should be fetched. Possible values: `home`, `notifications`. If not provided, an empty object will be returned.
|
|
|
|
#### Response
|
|
##### 200: OK
|
|
|
|
A request with `?timeline[]=home&timeline[]=notifications`
|
|
|
|
```json
|
|
{
|
|
"notifications": {
|
|
"last_read_id": "35098814",
|
|
"version": 361,
|
|
"updated_at": "2019-11-26T22:37:25.239Z"
|
|
},
|
|
"home": {
|
|
"last_read_id": "103206604258487607",
|
|
"version": 468,
|
|
"updated_at": "2019-11-26T22:37:25.235Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Save your position in a timeline {#create}
|
|
|
|
```http
|
|
POST /api/v1/markers HTTP/1.1
|
|
```
|
|
|
|
**Returns:** [Marker]({{< relref "entities/marker" >}})\
|
|
**OAuth:** User token + `write:statuses`\
|
|
**Version history:**\
|
|
3.0.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Form data parameters
|
|
|
|
home[last_read_id]
|
|
: String. ID of the last status read in the home timeline.
|
|
|
|
notifications[last_read_id]
|
|
: String. ID of the last notification read.
|
|
|
|
#### Response
|
|
##### 200: OK
|
|
|
|
Calling this API with home[last_read_id] causes a marker to be created for the home timeline.
|
|
|
|
```json
|
|
{
|
|
"home": {
|
|
"last_read_id": "103194548672408537",
|
|
"version": 462,
|
|
"updated_at": "2019-11-24T19:39:39.337Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
### 409: Conflict
|
|
|
|
If object is stale while being updated, an error will occur.
|
|
|
|
```json
|
|
{
|
|
"error": "Conflict during update, please try again"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
{{< page-relref ref="methods/timelines#home" caption="GET /api/v1/timelines/home (with `min_id` or `since_id` parameter)" >}}
|
|
|
|
{{< page-relref ref="methods/notifications#get" caption="GET /api/v1/notifications (with `min_id` or `since_id` parameter)" >}}
|
|
|
|
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/markers_controller.rb" caption="app/controllers/api/v1/markers_controller.rb" >}} |