Skip to content

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.

Responses
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

Responses
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.

Parameters
Name In Type Description
id (required) path string (uuid)

Invitation id.

Responses
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.

Parameters
Name In Type Description
id (required) path string (uuid)

Invitation id.

Request body, application/json: JourneyStart

Responses
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.

Responses
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.

Responses
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

Responses
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.

Parameters
Name In Type Description
day (required) path string (date)

The prompt’s day, as the caller’s calendar names it.

Responses
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.

Parameters
Name In Type Description
day (required) path string (date)

The prompt’s day, as the caller’s calendar names it.

Responses
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

Responses
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.

Responses
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