API reference
Every request and answer in the API, grouped, with its scope, its parameters and the objects it sends, drawn from the API's own description.
This page is drawn from the API’s own description, so it says what the API does. Errors, limits and scopes work the same way everywhere: see Requests, errors and limits. A field marked “required” must be sent, or in an answer is always there.
Account
Who this token is, what today is, what it may do, and the activity log.
| Request | What it does |
|---|---|
GET /v1/openapi.json |
This document |
GET /v1/me |
Today’s version, the next 14 days’ versions, and this token |
GET /v1/activity |
The activity log, newest first, without words |
DELETE /v1/token |
Revoke this token |
GET /v1/openapi.json
This document.
No token.
Answers 200 object.
GET /v1/me
Today’s version, the next 14 days’ versions, and this token. What a client needs to show the version and fire reminders offline, without ever working out a version itself. The birthday is never sent. Any token may read it.
Any token.
Answers 200 Me.
GET /v1/activity
The activity log, newest first, without words. What came in, changed and went out. It never carries a mail subject, mail words, another sender or a settings value. An Upcoming row’s title comes only with the upcoming scope.
Needs activity.
| Parameter | Where | Type | What it is |
|---|---|---|---|
before |
query | string | The next older page: next from the answer before. |
after |
query | string | Only rows newer than this one, an id the client has seen. |
from |
query | day | Only rows from this day on, in the account’s time zone (1.9.0). With to, at most 31 days. |
to |
query | day | Only rows up to the end of this day; left out, it is from. |
kinds |
query | string | Comma-separated families to keep. |
limit |
query | integer (1 to 100, 50 if left out) |
Answers 200 Activity.
DELETE /v1/token
Revoke this token. The token ends itself, as a sign-out does. Any token may.
Any token.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 204.
Notes
Add, read, change and delete notes.
| Request | What it does |
|---|---|
GET /v1/notes |
The notes this token wrote, or with notes:read or notes:all every note, on some days, oldest first |
POST /v1/notes |
Add a note |
GET /v1/notes/{date}/{id} |
Read a note this token wrote, or any note with notes:all |
PUT /v1/notes/{date}/{id} |
Replace the text of a note this token wrote, or any note with notes:all |
DELETE /v1/notes/{date}/{id} |
Delete a note this token wrote, or any note with notes:all |
POST /v1/notes/{date}/{id}/append |
Add a paragraph to a note this token wrote, or any note with notes:all |
GET /v1/notes
The notes this token wrote, or with notes:read or notes:all every note, on some days, oldest first. From from to to, days in the account’s time zone, both in, at most 31 days a request; a wider span is range_too_wide, so ask in pieces. Each note is as getNote reads it. A range with none is an empty list. Only this token’s notes, whatever else the days hold, unless it has notes:all (1.10.0) or notes:read (1.15.0): then every note on those days, or with mine=true its own alone. A page stops at about 1 MB (1.14.0), so it may hold fewer than limit: follow next until it is null.
Needs notes:write or notes:read.
| Parameter | Where | Type | What it is |
|---|---|---|---|
include |
query | urls |
urls puts each file’s address, and its small copy’s, in the answer, for one read rather than one for each file. They last 10 minutes and are fetched with no token (1.14.0). |
from (required) |
query | day | The first day. |
to |
query | day | The last day, from or later; left out, it is from. |
after |
query | string | The next page: next from the answer before. |
limit |
query | integer (1 to 100, 50 if left out) | |
mine |
query | true, false (false if left out) |
true keeps only the notes this token wrote (1.10.0). |
Answers 200 NoteList.
POST /v1/notes
Add a note. A note in the owner’s own voice, shown with “via <token name>” on the web. Hashtags in the text are its tags, in any script since 1.7.1. A text/plain body is the note’s text alone, and so is a form that is not a NoteForm; a multipart body is refused. With neither date nor written_at, it files to today. With uploads (and the media:write scope) it takes those files, and then needs no text. A place is a city from GET /v1/places or the place from POST /v1/places/here, sent back as it came, and kept as sent: its shape is checked, not the place.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NoteCreate; or text/plain: string; or application/x-www-form-urlencoded: NoteForm.
Answers 201 NoteWritten.
GET /v1/notes/{date}/{id}
Read a note this token wrote, or any note with notes:all. Its text and revision, so an app can pick up an edit made on the web. With notes:all (1.10.0), any note in the account, from any channel; source says where it was made and mine whether this token wrote it.
Needs notes:write or notes:read.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
include |
query | urls |
urls puts each file’s address, and its small copy’s, in the answer, for one read rather than one for each file. They last 10 minutes and are fetched with no token (1.14.0). |
Answers 200 Note.
PUT /v1/notes/{date}/{id}
Replace the text of a note this token wrote, or any note with notes:all. From the revision the client read: a note changed since is a 409 revision_mismatch with its current revision. No history is kept.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NoteEdit.
Answers 200 NoteWritten.
DELETE /v1/notes/{date}/{id}
Delete a note this token wrote, or any note with notes:all. With notes:all (1.11.0), any note in the account. The note goes with everything behind it, as on the web: its files, and for an emailed note the email.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 204.
POST /v1/notes/{date}/{id}/append
Add a paragraph to a note this token wrote, or any note with notes:all.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NoteAppend.
Answers 200 NoteWritten.
Files
Upload photos, recordings and PDFs, add them to notes, and fetch them.
| Request | What it does |
|---|---|
POST /v1/notes/{date}/{id}/media |
Add files to a note this token wrote, or any note with notes:all |
GET /v1/notes/{date}/{id}/media/{n} |
An address for one file on a note this token wrote, or any note with notes:all |
DELETE /v1/notes/{date}/{id}/media/{n} |
Take one file off a note this token wrote, or any note with notes:all |
POST /v1/uploads |
A signed form for one file |
POST /v1/notes/{date}/{id}/media
Add files to a note this token wrote, or any note with notes:all. With notes:all (1.11.0), any note in the account. Uploads from POST /v1/uploads, each checked against the bytes that arrived, up to 20 files on a note in all. It counts as a change. A note takes each upload once; a write refused or lost before it lands leaves the uploads for a retry with the same Idempotency-Key.
Needs media:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NoteMedia.
Answers 200 NoteWritten.
GET /v1/notes/{date}/{id}/media/{n}
An address for one file on a note this token wrote, or any note with notes:all. A signed address for the file, good for 10 minutes; fetch it with no token. With size=thumb, the small JPEG copy a photo has, for a list; a file without one is not_found. n is the number in the note’s media.
Needs notes:write or notes:read.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
n (required) |
path | integer (at least 1) | |
size |
query | thumb |
thumb for the small copy; left out, the file itself. |
Answers 200 NoteFile.
DELETE /v1/notes/{date}/{id}/media/{n}
Take one file off a note this token wrote, or any note with notes:all. The file goes with its small copy, transcript and description, and the note’s revision changes. The other files keep their numbers, and no later file takes this one. A note with no words can’t lose its last file: text_required, so delete the note instead. An emailed file stays in the note’s email, which no client can read, until the note is deleted. Since 1.17.0.
Needs media:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
n (required) |
path | integer (at least 1) | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 200 NoteWritten.
POST /v1/uploads
A signed form for one file. A photo, recording or PDF of up to 50 MB, its exact size given. Post the file to url as multipart/form-data, with every one of fields and then the file as file, within expires_in seconds, then name the upload in a note’s uploads. An account takes 200 files and 2 GB a UTC day, with the web’s. It has no receipt: a retry gets a new form, and an unused one expires.
Needs media:write.
Send application/json: UploadStart.
Answers 201 UploadForm.
Tags
The tag row and every tag.
| Request | What it does |
|---|---|
GET /v1/tags |
The tag row: pinned tags, then the most used lately |
PUT /v1/tags/pinned |
Replace the pinned tags |
GET /v1/tags/all |
Every tag with its name, notes, days, first day and last, Upcoming dates and check-ins, most used first |
GET /v1/tags
The tag row: pinned tags, then the most used lately. The pinned tags, then the tags used most in the last 30 days that aren’t pinned, ties broken by last use. A token that adds or reads notes may read it (any token before 1.22.0).
Needs notes:write or notes:read.
Answers 200 TagRow.
PUT /v1/tags/pinned
Replace the pinned tags. Up to 12 tags, normalized as note hashtags are (“#Running” is running, and since 1.7.1 “Москва” is москва), each once. The same pins show on the web and through every token.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: Pins.
Answers 200 TagRow.
GET /v1/tags/all
Every tag with its name, notes, days, first day and last, Upcoming dates and check-ins, most used first. getTags is the short list a compose screen offers; this is the whole archive’s. Needs notes:read or notes:all.
Needs notes:read or notes:all.
Answers 200 TagTotals.
Location
Find a city or the spot a device is at, and say where a note or a day was.
| Request | What it does |
|---|---|
PUT /v1/notes/{date}/{id}/place |
Say where a note this token wrote was, or any note with notes:all |
DELETE /v1/notes/{date}/{id}/place |
Take the place off a note this token wrote, or any note with notes:all |
PUT /v1/days/{date}/place |
Say where a day was, for the notes that day without a place |
DELETE /v1/days/{date}/place |
Take a day’s own place away |
GET /v1/places |
Find a city by name, for a note’s place |
POST /v1/places/here |
Name the spot a device is at, for a note’s place |
PUT /v1/notes/{date}/{id}/place
Say where a note this token wrote was, or any note with notes:all. A city from GET /v1/places, or the place from POST /v1/places/here, sent as it came. It replaces the one the note has, a photo’s too. The words and revision stay. The day’s weather follows, and never fails the write. Since 1.16.0.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NotePlaceWrite.
Answers 200 NoteWritten.
DELETE /v1/notes/{date}/{id}/place
Take the place off a note this token wrote, or any note with notes:all. The note then says no_place, shows no place from its day, and a photo’s spot won’t fill it in again. The words and revision stay. The day’s weather follows, and never fails the write. Since 1.16.0.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 200 NoteWritten.
PUT /v1/days/{date}/place
Say where a day was, for the notes that day without a place. A city from GET /v1/places, sent as it came; a day takes a city, not a device’s spot. It is what every note that day without a place shows, so it takes notes:all. The day’s weather follows, and never fails the write. Since 1.16.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: DayPlaceWrite.
Answers 200 DayPlaceWritten.
DELETE /v1/days/{date}/place
Take a day’s own place away. Its notes go back to what they showed without it. Removing a place the day doesn’t have is still a 204. The day’s weather follows, and never fails the write. Since 1.16.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 204.
GET /v1/places
Find a city by name, for a note’s place. The web’s city search. Send one of the answers as a note’s place, as it came.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
q (required) |
query | string (up to 80 characters) | A city’s name, like Zürich. |
Answers 200 Places.
POST /v1/places/here
Name the spot a device is at, for a note’s place. The city and neighbourhood, and the businesses Amazon Location finds within the accuracy (50 to 200 m), up to 6. Send place back as a note’s place, with venue set to one nearby name if the owner picks one; nothing is picked for them. An account names 100 spots a UTC day across its tokens. Nothing is kept until a note takes the place. It has no receipt: a retry asks again, and counts again.
Needs notes:write.
Send application/json: Spot.
Answers 200 Here.
Archive
Read the days, search, On this day, releases, the map, badges and the mail log.
| Request | What it does |
|---|---|
GET /v1/days |
The timeline, newest first: days with notes, an email, a pause or a place |
GET /v1/days/{date} |
One day: its version, notes, places, weather, and whether it was paused |
GET /v1/search |
Find notes by words or a tag, newest first |
GET /v1/on-this-day |
The same day of each earlier release, newest first |
GET /v1/releases |
Each year of life, newest first, with its days and notes |
GET /v1/releases/{v} |
One year of life in detail: its days, longest streak, tags and badges |
GET /v1/map/pins |
Where the notes were, as the Map’s pins, oldest first |
GET /v1/badges |
Earned badges and tracks, or show_badges false and nothing else |
GET /v1/mail-log |
What became of each email in the last 30 days, newest first |
GET /v1/days
The timeline, newest first: days with notes, an email, a pause or a place. What a day says of itself, a page at a time, as the web’s timeline lists them, with today on the first page. Its notes come from listNotes or getDay, so a page stays small. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
before |
query | day | Days before this one: next from the answer before. |
limit |
query | integer (1 to 100, 30 if left out) |
Answers 200 DayList.
GET /v1/days/{date}
One day: its version, notes, places, weather, and whether it was paused. A day from the birthday through today; any other is date_out_of_range. Its notes come oldest first and stop at about 1 MB: next goes on with listNotes as its after, with from set to this day. collected names the special days it collected, while Show badges is on. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
date (required) |
path | day | |
include |
query | urls |
urls puts each file’s address, and its small copy’s, in the answer, for one read rather than one for each file. They last 10 minutes and are fetched with no token (1.14.0). |
Answers 200 Day.
GET /v1/search
Find notes by words or a tag, newest first. Every word has to be in a note’s words, places, link names, transcripts or descriptions, as on the web. q or tag has to come. Reads the whole archive unless from and to narrow it, and counts as one read. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
include |
query | urls |
urls puts each file’s address, and its small copy’s, in the answer, for one read rather than one for each file. They last 10 minutes and are fetched with no token (1.14.0). |
q |
query | string | At most ten words or quoted phrases. |
tag |
query | string | A tag by any spelling: “Road Trip”, road-trip and #road-trip are one tag (1.21.0). |
from |
query | day | The first day; left out, the birthday. |
to |
query | day | The last day; left out, today. |
after |
query | string | The next page: next from the answer before. |
limit |
query | integer (1 to 100, 50 if left out) |
Answers 200 SearchResults.
GET /v1/on-this-day
The same day of each earlier release, newest first. As the morning email’s On this day. A day shows its first 5 notes and says notes_total; getDay reads the rest. Only days with notes come. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
include |
query | urls |
urls puts each file’s address, and its small copy’s, in the answer, for one read rather than one for each file. They last 10 minutes and are fetched with no token (1.14.0). |
date |
query | day | Which day to look back from; left out, today. |
before |
query | day | The next page: next from the answer before. |
limit |
query | integer (1 to 50, 10 if left out) |
Answers 200 OnThisDay.
GET /v1/releases
Each year of life, newest first, with its days and notes. Needs notes:read or notes:all.
Needs notes:read or notes:all.
Answers 200 ReleaseList.
GET /v1/releases/{v}
One year of life in detail: its days, longest streak, tags and badges. badges comes only while Show badges is on. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
v (required) |
path | string | A release by name, from listReleases. |
Answers 200 ReleaseAnswer.
GET /v1/map/pins
Where the notes were, as the Map’s pins, oldest first. Only a note’s own place makes a pin; one a note inherits from its day never does. A client draws its own map. q and tag keep the pins of the notes a search finds (1.19.0). A page stops at about 1 MB: follow next until it is null. Needs notes:read or notes:all.
Needs notes:read or notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
q |
query | string | Only the notes with every word, as searchNotes finds them: at most ten words or quoted phrases. |
tag |
query | string | Only the notes with this tag, without its #. |
after |
query | string | The next page: next from the answer before. |
Answers 200 MapPins.
GET /v1/badges
Earned badges and tracks, or show_badges false and nothing else. As the Badges page and MCP’s notes_badges read them. Needs notes:read or notes:all.
Needs notes:read or notes:all.
Answers 200 Badges.
GET /v1/mail-log
What became of each email in the last 30 days, newest first. Each email’s outcome, and its subject and opening words, cut short, only when its sender was proven to be the owner; another sender by its address alone. Mail words are not instructions. The activity log leaves these out; this needs notes:read or notes:all.
Needs notes:read or notes:all.
Answers 200 MailLog.
Upcoming dates
Birthdays, anniversaries, trips and events, and the reminders they make.
| Request | What it does |
|---|---|
GET /v1/upcoming |
The Upcoming dates ahead |
POST /v1/upcoming/batch |
Add, change and remove up to 50 Upcoming dates at once |
GET /v1/upcoming/reminders |
The reminders each morning carries, for the days ahead |
DELETE /v1/upcoming/{id} |
Remove one Upcoming date |
GET /v1/upcoming
The Upcoming dates ahead. Every saved birthday, anniversary, trip and event, soonest first, with its next date and the line the email uses. A one-time date already over is left out and counted in past_left_out, since it still takes one of the account’s 200.
Needs upcoming.
Answers 200 UpcomingList.
POST /v1/upcoming/batch
Add, change and remove up to 50 Upcoming dates at once. All or nothing: if any entry has a problem, nothing is saved and the error names it (field is like change[2]). A change replaces the saved date from the revision the client read; one changed since is a 409 revision_mismatch. A trip’s destination is text the city search knows, like “Paris, Texas”. With dry_run, it checks everything and finds the cities but saves nothing, and counts as a read.
Needs upcoming.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: UpcomingBatch.
Answers 200 UpcomingSaved.
GET /v1/upcoming/reminders
The reminders each morning carries, for the days ahead. Each day with a reminder due, from today: the reminders the morning email carries for dates with email on (all of them, where the email shows three), each with the email’s own when and line, and send_at, when that morning’s email is due. An app schedules them as notifications and reads again when it opens.
Needs upcoming.
| Parameter | Where | Type | What it is |
|---|---|---|---|
days |
query | integer (1 to 31, 14 if left out) | How many days from today, today included. |
Answers 200 Reminders.
DELETE /v1/upcoming/{id}
Remove one Upcoming date. From the revision the client read: a date changed since is a 409 revision_mismatch.
Needs upcoming.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
revision (required) |
query | integer (at least 1) | The revision last read. |
Answers 204.
Check-ins
The places the account stopped, and the names it remembers.
| Request | What it does |
|---|---|
GET /v1/check-ins |
The places you stopped, newest first |
POST /v1/check-ins |
Send a stop, as a phone is told of it |
DELETE /v1/check-ins |
Delete every check-in |
PATCH /v1/check-ins/{id} |
Name or tag a stay, or take its name away |
DELETE /v1/check-ins/{id} |
Delete a stay |
GET /v1/check-ins/places |
The places you remember |
POST /v1/check-ins/places |
Remember a place, or add a spot to a name |
GET /v1/check-ins/places/{id} |
One remembered place, and how many check-ins are there |
PATCH /v1/check-ins/places/{id} |
Rename a remembered place, or ignore it |
DELETE /v1/check-ins/places/{id} |
Forget a remembered place |
PATCH /v1/check-ins/places/{id}/check-ins |
Tag the check-ins already at a remembered place |
DELETE /v1/check-ins/places/{id}/check-ins |
Delete the check-ins at a remembered place |
GET /v1/check-ins
The places you stopped, newest first. A stay at a time, with its spot and the name it shows. Back-to-back stops at one place read as one, and ids lists the check-ins in it. from and to are your days, a stay going by when it began, up to 31 days; before is the next of an earlier page. A stay at an ignored place is hidden: left out here, in the activity log and from each read of one, until the place is unignored (1.20.0). A stay has the tags of every check-in in it (1.21.0). Since 1.18.0.
Needs activity.
| Parameter | Where | Type | What it is |
|---|---|---|---|
from |
query | day | First day, YYYY-MM-DD. |
to |
query | day | Last day; from if left out. |
before |
query | string | The next of an earlier page. |
tag |
query | string | Only the stays with this tag, by any spelling (1.21.0). |
limit |
query | integer (1 to 100, 50 if left out) | Stays a page holds. |
Answers 200 CheckIns.
POST /v1/check-ins
Send a stop, as a phone is told of it. Forward each report as it comes, with an Idempotency-Key. A later report with the same source and arrival, to the second, is the same stay: it fills in left and answers 200, not 201, so a client keeps no ids. A report with no arrival is matched by its left. A tap sends the moment it was tapped as arrived, and is never continued. Times over a week ahead are refused; older ones are fine, since a phone can be offline. The first 100 new stays a UTC day get their district, one paid lookup each, and those past that are still saved with none; RateLimit-Limit counts those. After 1000 reports a day, rate_limited. A new stop at an ignored place is not kept (1.20.0): it answers 200 with kept false and check_in as it would have read, its place naming the ignored place, and its id naming no check-in. A report filling in a stop kept before the place was ignored still lands. A new stop at a remembered place has that place’s tags (1.21.0). Since 1.18.0.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: CheckInReport.
Answers 200 CheckInReported, 201 CheckInReported.
DELETE /v1/check-ins
Delete every check-in. Needs ?confirm=all. Remembered places stay. One checkin.deleted row stays in the activity log with the count. Since 1.18.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
confirm (required) |
query | all |
all, to say you mean it. |
Answers 200 CheckInsDeleted.
PATCH /v1/check-ins/{id}
Name or tag a stay, or take its name away. A name on this stay alone, on every check-in in it, beating any remembered place. This token’s own, or any with notes:all. revision is the one you read. To name every stop at a spot, remember the place instead. Send name, tags or both (1.21.0): tags is the whole list, by name, set on every check-in in the stay. Since 1.18.0.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: CheckInName.
Answers 200 CheckInWritten.
DELETE /v1/check-ins/{id}
Delete a stay. Every check-in in the stay goes, and its row in the activity log. checkin.deleted stays there with its day and count, and never the place. This token’s own, or any with notes:all. Since 1.18.0.
Needs notes:write.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 204.
GET /v1/check-ins/places
The places you remember. Each name with its spots, and whether it is ignored (1.20.0). The nearest within 100 m names a stop. Since 1.18.0.
Needs activity.
Answers 200 NamedPlaces.
POST /v1/check-ins/places
Remember a place, or add a spot to a name. A name already in use, ignoring case, gains this spot and answers 200; a new one answers 201. It applies at once to every stop within 100 m, past and future. An account has up to 200 names, and a name up to 50 spots. ignored true ignores it as it is remembered, and false unignores it (1.20.0). tags join the place’s, and every new stop there gets them; when the place gains one, the answer counts its check_ins, to offer tagging them (1.21.0). Tags that would take the place past 20 are refused with invalid_request on tags, never cut (1.22.2). Since 1.18.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NamedPlaceWrite.
Answers 200 NamedPlaceWritten, 201 NamedPlaceWritten.
GET /v1/check-ins/places/{id}
One remembered place, and how many check-ins are there. check_ins counts the stays at it, hidden or not: a stay is at the remembered place nearest where it began. Show it before deleting them with DELETE /v1/check-ins/places/{id}/check-ins. Since 1.20.0.
Needs activity.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string |
Answers 200 NamedPlaceCounted.
PATCH /v1/check-ins/places/{id}
Rename a remembered place, or ignore it. Send name, ignored, or both. Every spot and stop follows a new name, and a name another place has is refused. Ignored (1.20.0, Jamie’s call): no new stop there is kept, and the stops already there are hidden, not deleted, from every list, the activity log and the Map. False brings them back. tags is the place’s whole list, by name, for the stops to come; the stops already there keep theirs. When it gains a tag, the answer counts its check_ins (1.21.0, Jamie’s call). Since 1.18.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: NamedPlaceName.
Answers 200 NamedPlaceWritten.
DELETE /v1/check-ins/places/{id}
Forget a remembered place. All its spots go, and stops there show their neighbourhood again. Forgetting an ignored place brings its stops back. Since 1.18.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Answers 204.
PATCH /v1/check-ins/places/{id}/check-ins
Tag the check-ins already at a remembered place. The tags sent join every stay at it, hidden or not; nothing else changes. If they would take any stay past 20 tags, nothing is written and the answer is invalid_request on tags (1.22.2). Offer it once, with the count, when a place gains a tag (Jamie’s call). count is the check_ins the place’s answer or GET /v1/check-ins/places/{id} gave, and a different number now is revision_mismatch with the new count. Answers how many stays were tagged; one checkin.tagged row goes in the log with the place’s id and that count. Since 1.21.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
Send application/json: PlaceCheckInsTag.
Answers 200 CheckInsTagged.
DELETE /v1/check-ins/places/{id}/check-ins
Delete the check-ins at a remembered place. Every stay at it, hidden or not, and their rows in the activity log; the place stays, ignored or not. count is the check_ins GET /v1/check-ins/places/{id} answered, and a different number now is revision_mismatch with the new count. One checkin.deleted row stays in the log with the place’s id and the count. Since 1.20.0.
Needs notes:all.
| Parameter | Where | Type | What it is |
|---|---|---|---|
id (required) |
path | string | |
Idempotency-Key |
header | string (up to 128 characters) | Any 1 to 128 printable ASCII characters, new for each change. Sent again with the same request, through this token or another of the account’s, it answers the first result again; with a different request it is a 422. |
count (required) |
query | integer (at least 0) | How many check-ins you were shown. |
Answers 200 CheckInsDeleted.
Objects
What the requests above send and answer.
Error
| Field | Type | What it is |
|---|---|---|
error (required) |
object |
Me
| Field | Type | What it is |
|---|---|---|
account (required) |
string | The account’s id: the same for every token of the account and never changing, so a client can tell whose account a token opens. It means nothing anywhere else. Since 1.4.0. |
today (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
tz (required) |
string | |
send_time |
string | When the morning email goes, local time. |
wrote_today |
boolean | |
streak |
integer (at least 0) | |
paused_until |
day or null | |
status |
active, stopped |
|
show_badges |
boolean | |
supporting_member |
boolean | Whether the account gets what Supporting Members of the Weekly Thing get, as Release Notes last looked (every nine days, and at a web sign-in); Changelog offers its other app icons by it. Since 1.12.0. |
lived |
object | Weeks and days lived, both from 1, as the Today page and the morning email set them (“Week 2,826 — Day 19,779”): day grows by one a day, and week is (day − 1) ÷ 7, rounded down, plus 1. Since 1.13.0. |
days (required) |
list of object | 14 days from today; a birthday shows as a new major or minor version on its day. |
token (required) |
object | |
api_version (required) |
string |
NoteCreate
Text, files or both.
| Field | Type | What it is |
|---|---|---|
text |
string (up to 20000 characters) | At most 20000 characters. Control characters other than tab and newline are dropped, and a lone surrogate escape is refused (since 1.7.0). |
date |
day | Any day from the birthday through today. Default: the day it was written. |
written_at |
time | When the words were typed, at most five minutes ahead. A note queued offline files to the day it was typed and is ordered by it. |
uploads |
Uploads | |
place |
NotePlace | |
markup |
rich or null |
rich when text holds rich-text marks; left out or null, the words are plain. An edit keeps it. Since 1.16.0. |
tags |
list of string (up to 20) | Tags by name, with spaces or emoji: “Road Trip”, “🚗 Lake”. A leading # is dropped. The hashtags in text are tags too, after these (1.21.0). |
NotePlaceWrite
| Field | Type | What it is |
|---|---|---|
place (required) |
NotePlace |
DayPlaceWrite
| Field | Type | What it is |
|---|---|---|
place (required) |
City |
DayPlaceWritten
| Field | Type | What it is |
|---|---|---|
date (required) |
day | A day in the account’s own time zone. |
place (required) |
NotePlaceRead |
NoteForm
A form, as a Shortcut’s Form body sends it, read as these fields when every name is one of them and text is there; any other form body is the words. Since 1.7.0.
| Field | Type | What it is |
|---|---|---|
text (required) |
string (up to 20000 characters) | At most 20000 characters. Control characters other than tab and newline are dropped, and a lone surrogate escape is refused (since 1.7.0). |
date |
day | Any day from the birthday through today. Default: the day it was written. |
written_at |
time | When the words were typed, at most five minutes ahead. A note queued offline files to the day it was typed and is ordered by it. |
NoteMedia
| Field | Type | What it is |
|---|---|---|
uploads (required) |
Uploads |
Uploads
Files posted to forms from POST /v1/uploads, each once. Needs media:write.
It is list of object.
UploadStart
| Field | Type | What it is |
|---|---|---|
name |
string (up to 255 characters) | The file’s name, which helps tell its type. |
type (required) |
string | A photo, recording or PDF’s media type. |
size (required) |
integer (1 to 52428800) | Its exact size in bytes. |
UploadForm
| Field | Type | What it is |
|---|---|---|
upload (required) |
string | |
type (required) |
string | The type it was signed for: name the upload with it. |
url (required) |
string | Where to post the file. |
fields (required) |
object | Every one goes in the form, before the file. |
expires_in (required) |
300 |
Seconds the form is good for. |
City
| Field | Type | What it is |
|---|---|---|
name (required) |
string | |
region (required) |
string | |
country (required) |
string | |
tz (required) |
string | |
lat (required) |
number | |
lon (required) |
number |
Places
| Field | Type | What it is |
|---|---|---|
places (required) |
list of City |
Spot
| Field | Type | What it is |
|---|---|---|
lat (required) |
number (-90 to 90) | |
lon (required) |
number (-180 to 180) | |
accuracy_m |
number (at least 0) | The device’s accuracy, in metres. |
DevicePlace
A spot, kept to six decimal places, with its names.
| Field | Type | What it is |
|---|---|---|
name (required) |
string | The city. |
region |
string | |
country |
string | |
tz |
string | |
district |
string | The neighbourhood, which names the note by default. |
venue |
string | A nearby name the owner picked. |
lat (required) |
number | |
lon (required) |
number | |
accuracy_m |
number | |
from (required) |
device |
NotePlace
A city from GET /v1/places, or the place from POST /v1/places/here, kept as sent: its names, time zone and spot are checked for shape, and it is never looked up again.
It is City or DevicePlace.
Here
| Field | Type | What it is |
|---|---|---|
place (required) |
DevicePlace | |
nearby (required) |
list of object (up to 6) |
NoteEdit
| Field | Type | What it is |
|---|---|---|
text (required) |
string (up to 20000 characters) | At most 20000 characters. Control characters other than tab and newline are dropped, and a lone surrogate escape is refused (since 1.7.0). |
revision (required) |
string | The revision last read, unchanged. |
tags |
list of string (up to 20) | The note’s whole list of tags by name, with the hashtags in text after them. Left out, it keeps the tags its old text didn’t carry (1.21.0). |
NoteAppend
| Field | Type | What it is |
|---|---|---|
text (required) |
string (up to 20000 characters) | At most 20000 characters. Control characters other than tab and newline are dropped, and a lone surrogate escape is refused (since 1.7.0). |
NoteWritten
| Field | Type | What it is |
|---|---|---|
note (required) |
object | |
unlocked |
list of object | Badges this note earned, only while Show badges is on, and never on a replay. |
Note
| Field | Type | What it is |
|---|---|---|
id (required) |
string | |
date (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
text (required) |
string | |
revision (required) |
string | |
written_at |
time or null | |
files |
integer (at least 0) | |
media |
list of NoteFileEntry | Its files, in order (1.9.0). |
token |
string or null | |
source |
string | Where the note was made: email, web, api and the rest (1.10.0). |
mine |
boolean | Whether this token wrote it (1.10.0). |
tags |
list of string | Its tags’ keys: “Road Trip” is road-trip (1.14.0; from the tags field too since 1.21.0). |
tag_names |
list of string | Its tags’ names as written, one for each of tags (1.21.0). |
markup |
rich or null |
rich when text holds rich-text marks, null when it is plain (1.14.0). |
parts |
list of string or object | Its words cut up to show them: strings, links by name and hashtags, in order (1.14.0). A rich note’s parts carry the marks as typed. |
place |
NotePlaceRead or null | The note’s own place, never one it inherits from its day (1.14.0). |
no_place |
boolean | The owner removed its place (1.14.0). |
edited_at |
time or null | When its words last changed, or null if they never have (1.14.0). |
tz |
string | The zone it was written in (1.14.0). |
late |
boolean | Written after the day it is filed on had ended (1.14.0). |
author |
user, assistant |
assistant when an agent wrote it, in its own voice (1.14.0). |
client |
string or null | The app or agent that sent it, by the name it gives itself (1.14.0). |
from |
string or null | What it was imported from, or null (1.14.0). |
attachments |
integer (at least 0) | How many files its email carried that Release Notes did not keep (1.14.0). |
NoteFileEntry
| Field | Type | What it is |
|---|---|---|
n (required) |
integer (at least 1) | Its number, for getNoteFile. |
kind (required) |
image, audio, file |
|
type (required) |
string | |
name (required) |
string or null | |
size (required) |
integer (at least 0) | Bytes. |
thumb (required) |
object or null | The small copy, when it has one: ask with size=thumb, or url here with include=urls (1.14.0). |
transcript |
string or null | A recording’s words, once the owner’s opt-in transcript is kept, up to 50,000 characters (1.14.0). Null until then, for a recording never written out, and when nothing could be made out. Reading never starts one, and one arriving does not change the note’s revision. |
description |
string or null | A photo’s description, once the owner’s opt-in one is kept, or null (1.14.0). |
writing |
boolean | A transcript of this recording is still to come (1.14.0). |
url |
string or null | With include=urls: the file’s address, fetched with no token (1.14.0). |
expires_in |
integer | With include=urls: seconds its addresses last (1.14.0). |
NotePlaceRead
| Field | Type | What it is |
|---|---|---|
label (required) |
string | The place as one line, as the web shows it. |
map |
string or null | |
venue |
string or null | |
district |
string or null | |
city |
string or null | |
region |
string or null | |
country |
string or null | |
lat |
number or null | |
lon |
number or null |
NoteList
| Field | Type | What it is |
|---|---|---|
from (required) |
day | A day in the account’s own time zone. |
to (required) |
day | A day in the account’s own time zone. |
items (required) |
list of Note (up to 100) | |
next (required) |
string or null | The after for the next page. |
DayHead
| Field | Type | What it is |
|---|---|---|
date (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
place (required) |
NotePlaceRead or null | The place set on the day itself. |
around (required) |
object or null | What a note with no place and no_place false shows: the day’s, or else home. |
weather (required) |
object or null |
DayList
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
tz (required) |
string | |
days (required) |
list of any | |
next (required) |
day or null | The before for the next page. |
weather_credit |
string | Show this wherever the weather shows. |
Day
| Field | Type | What it is |
|---|---|---|
date (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
place (required) |
NotePlaceRead or null | The place set on the day itself. |
around (required) |
object or null | What a note with no place and no_place false shows: the day’s, or else home. |
weather (required) |
object or null | |
today (required) |
boolean | This day is today. |
tz (required) |
string | |
paused (required) |
boolean | |
collected |
list of object | |
notes_total (required) |
integer | |
notes (required) |
list of Note | |
next (required) |
string or null | The after for listNotes. |
weather_credit |
string | Show this wherever the weather shows. |
SearchResults
| Field | Type | What it is |
|---|---|---|
terms (required) |
list of string | What was looked for, as it was read. |
tag (required) |
string or null | |
from (required) |
day | A day in the account’s own time zone. |
to (required) |
day | A day in the account’s own time zone. |
total (required) |
integer | Every note found, across every page. |
items (required) |
list of Note (up to 100) | |
next (required) |
string or null | The after for the next page. |
OnThisDay
| Field | Type | What it is |
|---|---|---|
date (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
days (required) |
list of object | |
next (required) |
day or null | The before for the next page. |
ReleaseList
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
releases (required) |
list of object |
ReleaseAnswer
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
release (required) |
object |
TagTotals
| Field | Type | What it is |
|---|---|---|
tags (required) |
list of object |
MapPins
| Field | Type | What it is |
|---|---|---|
notes (required) |
integer | Every note in the archive, placed or not. |
pins (required) |
list of object | |
next (required) |
string or null | The after for the next page. |
Badges
While show_badges is true, what the Badges page reads too: what is earned, and the tracks.
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
version (required) |
string | |
show_badges (required) |
boolean |
MailLog
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
tz (required) |
string | |
entries (required) |
list of object |
NoteFile
| Field | Type | What it is |
|---|---|---|
url (required) |
string | |
type (required) |
string | |
expires_in (required) |
600 |
TagRow
| Field | Type | What it is |
|---|---|---|
pinned (required) |
list of string (up to 12) | Their keys. |
pinned_names (required) |
list of string (up to 12) | Their names, as pinned (1.21.0). |
recent (required) |
list of object (up to 20) | |
window_days (required) |
30 |
Pins
| Field | Type | What it is |
|---|---|---|
pinned (required) |
list of string (up to 12) |
UpcomingFields
A date as it is saved. A change sends every field again, as it should be.
| Field | Type | What it is |
|---|---|---|
kind (required) |
birthday, anniversary, trip, event |
|
title (required) |
string (up to 120 characters) | One line. |
tags |
list of string (up to 20) | Its tags by name, the whole list, like [“Family”, “Road Trip”] (1.21.0). A leading # is dropped; “Road Trip” and “road trip” are one tag. |
tag_names |
list of string | The names of its tags, as tags lists their keys (1.21.0). |
tag |
string or null | Its first tag’s key. Deprecated in 1.21.0, gone in the next release: send tags. Sent alone, it names the first tag and keeps the others. |
date (required) |
string | MM-DD for a birthday or anniversary; YYYY-MM-DD for a trip (its first day) or an event. |
year |
integer or null | A birthday’s or anniversary’s first year, so the line can say which one it is. |
end_date |
day or null | A trip’s last day, on or after date. |
place |
string or null | A trip’s destination: “Zürich”, or “Paris, Texas” to choose among cities of one name. |
email |
boolean (true if left out) | Remind in the morning email (and so in apps). |
reminders |
list of integer (up to 6) | Days before to remind; by default 7, 1 and 0 (a trip 14, 1 and 0). |
Upcoming
| Field | Type | What it is |
|---|---|---|
kind (required) |
birthday, anniversary, trip, event |
|
title (required) |
string (up to 120 characters) | One line. |
tags |
list of string (up to 20) | Its tags by name, the whole list, like [“Family”, “Road Trip”] (1.21.0). A leading # is dropped; “Road Trip” and “road trip” are one tag. |
tag_names |
list of string | The names of its tags, as tags lists their keys (1.21.0). |
tag |
string or null | Its first tag’s key. Deprecated in 1.21.0, gone in the next release: send tags. Sent alone, it names the first tag and keeps the others. |
date (required) |
string | MM-DD for a birthday or anniversary; YYYY-MM-DD for a trip (its first day) or an event. |
year |
integer or null | A birthday’s or anniversary’s first year, so the line can say which one it is. |
end_date |
day or null | A trip’s last day, on or after date. |
place |
string or null | A trip’s destination: “Zürich”, or “Paris, Texas” to choose among cities of one name. |
email |
boolean (true if left out) | Remind in the morning email (and so in apps). |
reminders |
list of integer (up to 6) | Days before to remind; by default 7, 1 and 0 (a trip 14, 1 and 0). |
id (required) |
string | |
revision (required) |
integer | Send it back to change or remove the date. |
next (required) |
day | Its next date, or today while a trip is on. |
through |
day | A trip’s last day this time. |
status (required) |
upcoming, today, ongoing, past |
|
line (required) |
string |
UpcomingList
| Field | Type | What it is |
|---|---|---|
today (required) |
day | A day in the account’s own time zone. |
entries (required) |
list of Upcoming | |
past_left_out (required) |
integer (at least 0) | |
max_entries (required) |
200 |
UpcomingBatch
At most 50 entries in all, and at least one.
| Field | Type | What it is |
|---|---|---|
add |
list of UpcomingFields | |
change |
list of any | |
remove |
list of object | |
dry_run |
boolean (false if left out) |
UpcomingSaved
| Field | Type | What it is |
|---|---|---|
dry_run (required) |
boolean | |
added (required) |
list of Upcoming | In the order they were sent, with their ids. |
changed (required) |
list of Upcoming | |
removed (required) |
list of string | The ids removed. |
unlocked |
list of object | Badges this save earned, only while Show badges is on, and never on a replay. |
Reminders
| Field | Type | What it is |
|---|---|---|
from (required) |
day | A day in the account’s own time zone. |
through (required) |
day | A day in the account’s own time zone. |
days (required) |
list of object | Only the days with a reminder due. |
CheckIn
A stay: one check-in, or back-to-back ones at one place.
| Field | Type | What it is |
|---|---|---|
id (required) |
string | Its first check-in’s id; any in ids names the stay. |
ids (required) |
list of string | The check-ins in it, oldest first. |
at (required) |
time | When it began, or when it was first heard of. |
arrived (required) |
time or null | Null if unknown. |
left (required) |
time or null | Null while still there, and for a tap. |
lat (required) |
number | |
lon (required) |
number | |
accuracy_m |
number or null | The circle’s radius. |
time_zone |
string or null | The zone there. |
day (required) |
day | A day in the account’s own time zone. |
source (required) |
visit, tap |
|
label (required) |
string | The name it shows. |
named_by (required) |
own, place, district, none |
How label came about. |
place |
string or null | The remembered place naming it. |
name |
string or null | A name on this stay alone. |
district |
string or null | Neighbourhood and city. |
via |
string or null | |
token |
string or null | |
token_id |
string or null | |
client |
string or null | |
tags |
list of string | The keys of the tags of every check-in in it; left out for none (1.21.0). |
tag_names |
list of string | Their names (1.21.0). |
revision (required) |
integer | Send it back to name this stay. |
CheckIns
| Field | Type | What it is |
|---|---|---|
items (required) |
list of CheckIn | |
next (required) |
string or null | The before for the next older page. |
CheckInWritten
| Field | Type | What it is |
|---|---|---|
check_in (required) |
CheckIn |
CheckInReported
| Field | Type | What it is |
|---|---|---|
check_in (required) |
CheckIn | |
kept |
boolean | False when the stop was at an ignored place and nothing was kept; its check_in names no check-in. Since 1.20.0: an answer replayed from before then leaves it out, which means true. |
CheckInsDeleted
| Field | Type | What it is |
|---|---|---|
deleted (required) |
integer |
CheckInsTagged
| Field | Type | What it is |
|---|---|---|
tagged (required) |
integer |
PlaceCheckInsTag
| Field | Type | What it is |
|---|---|---|
tags (required) |
list of string (up to 20) | The tags to add, by name. |
count (required) |
integer (at least 0) | How many check-ins you were shown. |
CheckInReport
| Field | Type | What it is |
|---|---|---|
arrived |
time or null | Null if unknown. |
left |
time or null | Null while still there. |
lat (required) |
number (-90 to 90) | |
lon (required) |
number (-180 to 180) | |
accuracy_m |
number or null | |
time_zone |
string or null | An IANA name; the account’s if left out. |
source (required) |
visit, tap |
CheckInName
| Field | Type | What it is |
|---|---|---|
name |
string or null | |
tags |
list of string (up to 20) | The stay’s whole list of tags by name; [] for none (1.21.0). |
revision (required) |
integer (at least 1) |
NamedPlace
| Field | Type | What it is |
|---|---|---|
id (required) |
string | |
name (required) |
string | |
spots (required) |
list of object | |
ignored |
boolean | No stop here is kept, and those kept already are hidden. Since 1.20.0. |
tags |
list of string | The keys of the tags each new stop here gets; left out for none (1.21.0). |
tag_names |
list of string | Their names (1.21.0). |
revision (required) |
integer |
NamedPlaceCounted
| Field | Type | What it is |
|---|---|---|
place (required) |
any |
NamedPlaces
| Field | Type | What it is |
|---|---|---|
places (required) |
list of NamedPlace |
NamedPlaceWritten
| Field | Type | What it is |
|---|---|---|
place (required) |
any |
NamedPlaceWrite
| Field | Type | What it is |
|---|---|---|
name (required) |
string (up to 100 characters) | |
lat (required) |
number (-90 to 90) | |
lon (required) |
number (-180 to 180) | |
ignored |
boolean | Ignore the place, or unignore it. Left out, as it was. Since 1.20.0. |
tags |
list of string (up to 20) | Tags to join the place’s, by name (1.21.0). |
NamedPlaceName
| Field | Type | What it is |
|---|---|---|
name |
string (up to 100 characters) | |
ignored |
boolean | Ignore the place, or unignore it. Since 1.20.0. |
tags |
list of string (up to 20) | The place’s whole list of tags by name; [] for none (1.21.0). |
Activity
| Field | Type | What it is |
|---|---|---|
items (required) |
list of ActivityRow | |
next (required) |
string or null | The before for the next older page. |
ActivityRow
One thing that happened. Each kind keeps its own fields (note.added has day and note; a reads row calls and tools; a checkin checkin, label, arrived, left and source, and never a spot, its label being the one place a row holds your own words); via says through what, and a token’s rows name it as token and, from 1.4.0, by id as token_id.
| Field | Type | What it is |
|---|---|---|
id (required) |
string | A cursor for before and after. |
at (required) |
time | |
kind (required) |
string | Its family is one of mail, reads, note, transcript, description, import, badge, email, reminder, place, upcoming, settings, pause, status, signin, export, photo, address, calendar, connection, feedback, egg, checkin, account. |
via |
string | |
token |
string | The name of the token it came through. |
token_id |
string | The id of the token it came through, as GET /v1/me gives it. Absent on rows written before 1.4.0, and on rows no token wrote. |
client |
string |