API reference: journey
The Journey Companion. A year of daily prompts, fixed to the calendar, each person’s own journey of private entries, and a companion to walk it with, who sees which days are written and can send a nudge with no words in it. Entries are notes, sealed like any other and marked as entries only inside their sealed metadata, so the server never learns which notes are entries. It holds each journey’s first day and year, the days written as dates alone, the companionship and its invitations, and the reminder email.
DELETE /v1/companionship
Ends the caller's companionship, from either side. Needs a session.
The other is told by email. The link, its progress and nudges end, and so does a companion’s Orbit. Each keeps every entry and may carry on to day 365 on their own plan.
| Status | Description | Body |
|---|---|---|
| 204 | Ended. | |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No companionship | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
POST /v1/companionship/invitations
Invites a companion by handle or email address. Needs a session.
Only a paying Orbit member invites: a companion’s Orbit does not. One companionship at a time, and one invitation pending, which expires after 14 days.
An invitation by handle reaches that account in the app. One by email reaches the address: an account that has verified it finds the invitation in the app, and anyone else is asked to join for free, then accept. The answer is the same either way, so it never says whether an address has an account.
Request body, application/json: InvitationRequest
| Status | Description | Body |
|---|---|---|
| 201 | Invited. | Invitation application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 402 | No Orbit of the caller’s own | Problem application/problem+json |
| 404 | No account has the handle | Problem application/problem+json |
| 409 | A companionship or an invitation already | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
DELETE /v1/companionship/invitations/{id}
Withdraws an invitation the caller sent, or declines one sent to the caller. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Invitation id. |
| Status | Description | Body |
|---|---|---|
| 204 | Withdrawn or declined. | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No such invitation pending | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
POST /v1/companionship/invitations/{id}/acceptance
Accepts an invitation sent to the caller, starting the companionship. Needs a session.
The companion’s journey starts on firstDay, the caller’s calendar day, with that day’s prompt, unless their own journey is already under way. The companion has Orbit while the companionship lasts and the inviter keeps paying for theirs.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Invitation id. |
Request body, application/json: JourneyStart
| Status | Description | Body |
|---|---|---|
| 200 | The caller’s journey and companion, now. | JourneyView application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No such invitation pending for the caller | Problem application/problem+json |
| 409 | Either already has a companion | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
POST /v1/companionship:nudge
Sends the companion a nudge, with no words in it. Needs a session.
The companion sees when they were last nudged, in their journey’s view. One nudge a day each way.
| Status | Description | Body |
|---|---|---|
| 204 | Nudged. | |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No companionship | Problem application/problem+json |
| 429 | Today’s nudge already sent | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
GET /v1/journey
The caller's journey, their companion's progress, invitations and reminder. Needs a session.
| Status | Description | Body |
|---|---|---|
| 200 | The caller’s journey as it stands. | JourneyView application/json |
| 401 | No valid session token | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
POST /v1/journey
Starts the caller's journey on `firstDay`, the caller's calendar day. Needs a session.
Starting one is free, on every plan. A journey under way carries on to day 365 whatever the plan.
Request body, application/json: JourneyStart
| Status | Description | Body |
|---|---|---|
| 201 | Started. | Journey application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 409 | A journey is under way | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
PUT /v1/journey/days/{day}
Records that the caller wrote the prompt of `day`. Needs a session.
A date, never words: the entry itself is a note, sealed like any other. The day lies between the journey’s first day and today, and a missed one can be written any time in the year. Only the companion sees which days are written.
| Name | In | Type | Description |
|---|---|---|---|
day (required) | path | string (date) | The prompt’s day, as the caller’s calendar names it. |
| Status | Description | Body |
|---|---|---|
| 204 | Recorded. | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 409 | No journey under way | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
DELETE /v1/journey/days/{day}
Records that the caller's entry for `day` is gone, so the day reads as unwritten. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
day (required) | path | string (date) | The prompt’s day, as the caller’s calendar names it. |
| Status | Description | Body |
|---|---|---|
| 204 | Recorded. | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 409 | No journey under way | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
PUT /v1/journey/reminder
Sets the daily reminder email, off unless turned on. Needs a session.
A short email at time in timeZone, saying today’s prompt is ready, to the account’s verified address, on the first 7 days after the last day written or the day it was turned on. Once 3 in a row go unanswered by a read of the journey or a day written, they pause, and setting it again ends the pause. From the 8th quiet day, one fresh-start email goes on the next Monday or 1st instead, and then none until a day is written. Apple devices remind with a notification of their own instead, which nothing here sends.
Request body, application/json: JourneyReminder
| Status | Description | Body |
|---|---|---|
| 200 | The reminder as set. | JourneyReminder application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
POST /v1/journey:anotherYear
Chooses another year, once day 365 is reached. Needs a session.
With a companion, both must choose: the second choice starts year two for both, and the companionship and a companion’s Orbit go on for another year. Alone, on any plan, it starts year two at once. Year two’s first day is the day after year one’s last.
| Status | Description | Body |
|---|---|---|
| 200 | The caller’s journey and companion, now. | JourneyView application/json |
| 401 | No valid session token | Problem application/problem+json |
| 409 | The year isn’t complete, or there’s no journey | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |