Fernscout API

Always answers 202, whether or not the address owns anything — so it cannot be used to discover which addresses exist. Two exceptions, and neither of them varies with the address: an agent code for an address that neither owns the journal nor is on the trip you named answers 403 rather than leaving you waiting for a code that was never coming, and a server with mail switched off answers 503 mail_disabled rather than issuing a code it has no way to deliver.

A new request invalidates the previous code. Two of these mails look identical apart from the time in them, and only the newest code works — so if you ask twice, make sure the person reads out the newest one.

This deletes nothing. It answers 202 and mails the address that owns the journal a link to a page with a button; only that button deletes. The link is single-use, expires in an hour, and the caller cannot follow it — that is the point, because the confirmation for something irreversible must not be completable by the same agent that asked for it. Report that a mail is waiting, never that the journal is gone. Owner only: a trip-scoped token is refused.

Added because five fields POST .../trips invites you to set — accent, costsVisibility, intro, translations, test — could be written and read back nowhere: the trips list is a summary and the dedicated doors cover only visibility, rates, people, travellers and tracks. Read your own work back with this before telling somebody a trip is ready. "It was accepted" is not the same claim as "it is there", and this API has been wrong about the difference. Gated as a write is rather than as a read, because it carries people, which is addresses.

Five fields of a trip nothing could write until B622 (four) and B245 (cover): title, tagline, start, end and cover. Send only what is changing. A title cannot be cleared — a trip.md without one does not load — while an emptied tagline or a cover sent as null/"" removes the key rather than storing an empty one. Dates are YYYY-MM-DD, and end may not precede start: the check is against the result, so either date may arrive on its own. cover must be a src this trip's own gallery already carries — read GET .../trips/{trip}/media for the list — since a value naming a photo the trip does not have would render as a broken image on the trips index and the OG card.

Only the frontmatter lines you name are rewritten. The prose under it, the key order, and every other key are left byte for byte, so this is safe on a trip.md somebody wrote by hand.

Owner only. A trip-scoped token belongs to somebody who was on the journey, and adding a day to it is not the same authority as saying what it is called.

This deletes nothing — same flow as deleting a journal. One difference worth repeating to the person: deleting a day leaves its photographs on disk, and deleting a trip takes them with it. Owner only; somebody listed in the trip's people: may write days into it and may not delete it.

The button on the confirmation page. There is deliberately no GET: mail scanners and link previewers follow links, and a GET that destroyed a journal would eventually be followed by a robot. The token is the credential and it arrived in the owner's mailbox — an agent holding it has read somebody's mail and should not be using it.

A name, a town and a country each — and never a street. An agent addresses a card by contactId and never holds anybody's home address, which is what makes it impossible to post one to an address that was invented or mistyped in a conversation.

Everybody here is an active contact of this journal who asked for a real postcard and left an address themselves. Owner only.

Writes a draft order and answers with a URL. It charges nothing and prints nothing.

There is deliberately no endpoint that sends. Not an owner-only one — none at all: the send is a button on the page this returns, because printing and posting spends real money and ends up in somebody's letterbox, which is not a decision to take on their behalf. Hand the url over and stop; do not report the cards as sent, or as being sent. GET .../postcards/{id} says later whether they went.

Owner only, and the recipients must be ids from .../postcards/recipients.

draft is waiting for a person, expired is past its week, printed means the cards went to a printer — which is not the same as delivered, and nothing here will ever know that. Owner only.

Never the tokens: only their hashes were stored, so a link that was lost has to be reissued rather than looked up. Owner only.

Neither link grants anything. Whoever opens one proves their own address and lands in the owner's approval queue; the owner lets each person in by hand. So a link is an invitation to ask, and reporting one as "they now have access" is false.

guest leads to reading the journal — every trip marked visibility: guest, and never one marked private. It is journal-wide; there is no per-trip guest link. Safe to forward.

buddy needs a trip and leads to write access to that trip, plus the journal's guest trips once approved. It is for the people who were actually on the trip and is not the one to paste into a group chat — say which kind you are handing over.

The token appears in this response once and is stored only hashed. Owner only: a trip-scoped token may write days into its trip and may not invite people to it.

The link stops working and everybody already approved stays in — which is the whole reason these exist rather than a shared password, which could only be changed for everyone at once. Nothing anybody wrote is removed, so unlike deleting a journal or a trip this needs no mailed confirmation.

public (anyone, and listed) · guest (the journal's approved guests, plus the trip's own people) · private (only the trip's own people, not approved guests). Omitted means this journal's own answer — public in a public journal, guest in a guest one — so a forgotten field is never wider than the journal already is; a value this server does not recognise falls back to private instead. Ask rather than relying on either, and recommend public or guest.

A private trip stays shut to approved guests too — approving somebody into the journal does not open it, and the owner has no way to grant it per person. If the plan is to share with family, guest is the value, and approving them is the other half of it.

Takes the signup token. Answers with an agent token for the journal it just created, so the caller can go straight on to creating a trip.

Not only the published ones, whatever this summary said until B540: a draft comes back flagged draft: true, because an agent reading a trip back needs to see what it has written and not yet put on the site.

Always creates a draft. A retry that finds its own earlier write gets 409 rather than overwriting it — send an idempotency_key to get the first answer back instead. Photographs are not part of this body: POST them to the media endpoint, which adds them to the day.

Refused the first time on purpose. The first call answers 409 with a signed confirm code and a question; repeat the call with that code to go through. The code is bound to the journal, trip, day and verb, and lasts five minutes. A published day is a different verb from a draft, so a code issued for one will not verify against the other. The entry file is removed; its photographs are left on disk.

Puts a draft on the site, in one call. Ask the person first, in words, and wait for an answer. Nothing here can check that you did, so that sentence is the whole of the safeguard: publishing is your work to do, and deciding is theirs.

Owner only: a token scoped to a single trip writes days into it and cannot put them on the site. Nothing sent to the days POST can publish — writing and publishing are two calls, which is what gives them a moment to read the day back, and it is the only part that is structural.

Not an update. This does exactly one thing — remove the line holding a day back — and it is not how you correct a day, before or after it is on the site: that is PATCH .../days/{slug}. A day already published answers 409 here rather than accepting new content under the name "publish".

It does not really come back. Taking a day down removes it from the journal, the feed and the search index, not from the people who have read it.

send_mail: true sends a letter about this day to every reader who may see it, in their own language — B345. Its absence means no letter, and that default never changes: publishing several days must not mail one letter per day to everybody the owner knows. The response's mail field reports how many went, never who to. A failed send never fails the publish; it shows up in mail instead. Owner only, same as the publish itself. See /api/v1/{user}/trips/{trip}/days/{slug}/send-mail to send it again afterwards.

send_whatsapp: true does the same on WhatsApp — B365 — and obeys the same default: absent means nothing is sent. Both flags may be given at once, and each reports separately (mail, whatsapp) so one channel failing tells you nothing false about the other. Its readers are a narrower set: only contacts who ticked the WhatsApp box and left a usable number, because Meta requires opt-in to WhatsApp specifically and the digest's consent does not carry over.

Both flags must be the JSON boolean true — B400. "send_mail": "true" (a string) or 1 is not read as yes; it is ignored the same as if it had never been sent, and nothing goes out for it. That case is reported rather than left silent: the response carries flagsIgnored (e.g. ["send_mail"]) and a flagsIgnoredMessage naming which key was present but not a boolean. Absence of the key stays silent — that is the honest "did not ask" — only a present, wrong-typed value is called out.

Sending costs credits where this server charges for them — B366, one per email and one per WhatsApp message. Both requested channels are priced together against one balance before anything is published: if the journal cannot cover the whole send, this answers 402 with needed and balance, the day stays a draft and nothing is sent. It is all-or-nothing, so a partial delivery is never the outcome. A publish with neither flag is never charged and never refused for credits. GET /api/v1/{user}/status carries the balance; read it first rather than discovering an empty account here. Only the journal's owner can add credits, and only from a shell on the server — there is no purchase call, so a 402 is a message to pass on, never something to retry around.

B345's second trigger: mail every entitled reader about a day that is already on the site, whether this is the first attempt or a repeat. Owner only, for the same reason /publish is — a token scoped to one trip may write days into it and must not be able to mail the journal's whole readership.

Not idempotent, on purpose. Every call sends to everybody who currently qualifies, whatever an earlier attempt sent — the owner asking again is the whole of the safeguard, so ask in words before calling it a second time, the same discipline as /publish itself. The response says resend: true and how many letters went; never who to. A test: true day, or one still a draft, refuses outright rather than sending nothing quietly.

B365, and the exact counterpart of /send-mail beside it: message every entitled reader who opted in to WhatsApp about a day already on the site. Owner only, and that reasoning is stronger here than for mail — a letter waits in an inbox, this buzzes in somebody's pocket, and a reader who did not want it reports the number rather than unsubscribing. Meta bans the number and the journal loses the channel for everyone.

Not idempotent, on purpose, exactly like /send-mail. The response says resend: true and how many went; a failure names its reason against a masked number, never the number itself. A test: true day, or one still a draft, refuses outright.

The words are fixed: WhatsApp permits only a template approved by Meta in advance, so this fills variables in sentences already written. no_template means readers opted in but no approved template exists for any language they could be written in.

The whole entry — content, gallery, costs, tags, translations, and without for anything the day deliberately has none of — and a status of draft or published. This is how you read back something you have just written, before telling a person it is ready — translations included, in the same shape they were written in. Scoped like the writes on this path: a draft is what somebody has not decided to publish, so it needs the same token.

Change one or more fields of a day already written — a coordinate that was missing, a misspelled place, a date that was wrong. This is a textual edit: a field this omits, and the file's own formatting, are left exactly as they were — the same discipline POST .../media and the publish call already keep.

Not how you publish or unpublish. There is no status in the body (components.schemas.DayEdit), and sending one is refused (400) with nothing written — a day moves between draft and published only through POST .../publish, never through this call. The response's status says which one the day was left in, so it can be reported truthfully rather than assumed: an earlier agent had no way to edit a day, reached for /publish because it was the only verb that touched an existing file, and put fifteen unreviewed days on somebody's site while reporting them as drafts (B266).

Same authority as writing the day: whoever may POST a day into this trip may PATCH one, trip-scoped tokens included.

The whole of costs.md — the budget, the preparation costs, the base currency they default into, and the trip's own prose about the money. exists: false means there is no costs.md yet, which is not an error: it is the same answer an empty drafts list gives. This is how you read back what PUT or PATCH just wrote, before telling the owner it is there.

Same authority as writing a day: whoever may write to this trip may read its budget, trip-scoped tokens included.

Textual, like PATCH .../days/{slug} (B266): a field this omits, and the file's own formatting — comments, key order, flow or block YAML style — are left exactly as they were, because this may well be a file the owner wrote by hand.

budget, costs and body each replace their own block wholesale when sent. budget: null clears the budget alone and leaves costs and body untouched; costs: [] clears the preparation-costs list the same way. Neither removes costs.md itself — that is DELETE, below, and it is the only call that makes the costs page disappear.

Same authority as writing a day: whoever may POST a day into this trip may PATCH its costs, trip-scoped tokens included.

Whole file, not just the budget: line: the costs page is presence-driven (B293) and hasCostsData (B267, widened B328) is what decides it exists, by asking whether costs.md is there or any day carries its own costs: block — so removing the file takes the budget away but leaves the page standing if a day still logs spend (B332). The response's costsPageGone says whether the page actually went, rather than leaving that to be inferred.

Not idempotent in status: calling this on a trip with no costs.md answers 404, since there was nothing here to remove.

Same authority as writing a day: whoever may write to this trip may remove its budget, trip-scoped tokens included.

Creates or wholly replaces a trip's budget, preparation costs and prose about the money, in one call — the write half of B295: before it, a budget could only be written by hand, over SSH or with the add-a-trip skill on a local checkout, and there was no way over the network to give a trip its costs page at all.

budget is required. A zero or missing total is refused here with a problems entry, rather than written and read back as no budget at all — lib/costFormat.ts's parseBudget drops one silently for a page render, and a door cannot repeat that (B263).

Same authority as writing a day: whoever may POST a day into this trip may PUT its costs, trip-scoped tokens included — a budget is trip content, and the people on a trip are the people who spent the money.

The rates: table on this trip's trip.md — units of the journal's base currency for one unit of each keyed currency, so {"THB": 0.0245} reads "1 THB = 0.0245" of the base. A currency with no rate is simply absent; its costs are reported as unconverted rather than guessed at.

createTrip could only ever write rates: once, at the moment a trip is made (B207); this is the door to fix or fill in a rate afterwards, for a hosted instance where nobody has a shell to edit trip.md by hand.

Merges, does not replace. Naming one currency fills in or corrects that one and leaves every other rate already on the trip untouched — send the one rate a trip is missing, not the whole table. Costs already recorded in a currency you just add convert the next time the costs page, or any total drawn from it, is read.

Owner only, like rates at creation — a trip-scoped token is refused with out_of_scope: a rate table is metadata about the trip, the same shelf visibility and people sit on, and not content a traveller logs. That is unlike the trip's budget, which anyone on the trip may write.

visibility: and listed: on this trip's trip.md — private (the people who were there, and the owner), public (everyone) or guest (everyone the owner has approved into the journal, and the people who were there), and whether the trip is advertised in the sitemap, the feed and the trip switcher — plus teaser:, whether a closed trip is named on the trips page without being opened.

createTrip could only ever write visibility: once, at the moment a trip is made (B207); this is the door to change it afterwards, for a hosted instance where nobody has a shell to edit trip.md by hand — the contacts page's own advice, "set a trip's visibility to guest", had nowhere else to send an owner.

Send only what changes — visibility, listed, teaser, or any of them. An unrecognised visibility is refused rather than written and read back as private later, the same rule the file's own reader already follows. listed: true is refused on a trip whose visibility does not already advertise it (B51) — only public does, and teaser: true is refused on a public trip for the mirror reason: it names a trip nobody may read, and a public trip is readable.

Widening is said out loud. Moving towards public, or from private to guest, exposes every day already published on this trip to a wider audience the instant this call returns; the response's note says so. Narrowing needs no such warning: it can only take readers away.

Owner only, like visibility at creation — a trip-scoped token is refused with out_of_scope: this is metadata about the trip, the same shelf rates and people sit on, and deciding who else may read the whole journey is not the authority writing a day into it grants.

costs, coordinates and photos, each true unless the owner has turned it off. A day that says nothing about a tracked row is refused with 422 incomplete_day — send the thing, or say in the same call that the day does not have it. Read this before writing days rather than after the first refusal.

Send {"tracks": {"costs": false}} — only the rows you name change. Turning a row off is the owner deciding this journey is not keeping that; it is not a way to quieten one awkward write, which is what the per-day decline is for. Nothing already written changes either way.

The journal's inbox: files that have been uploaded and belong to no day yet. Grouped by kind — media, files, photobook, postcards — with each file's id, the name it arrived under, its size, and whatever the uploader said about it (description, caption, lat, lon, takenAt, tags; absent means nobody said).

Make this call before writing days for a trip somebody has just come back from: the pictures are usually here already. Filing one into a day is POST /api/v1/{user}/trips/{trip}/media with inbox.

A trip-scoped token is refused — the bucket belongs to the journal, and showing it would show files staged for trips you are not on.

The one upload door that does not ask which day a file is for. That is what it is for: a camera emptied on the evening it happened, when the days that will hold the pictures are still unwritten.

multipart/form-data. files may repeat; meta and kind may repeat alongside it, one per file and in the same order. Everything on meta is optional and every field of it is what you were told — never what you concluded from looking at the file. A file with no description is normal; an invented one is not recoverable.

Duplicates are free. A file is named by a hash of its own bytes, so the same file sent twice is stored once and the second call answers with the first one's id and duplicate: true. Two different files sharing a name both survive.

Counts against the journal's storage ceiling like everything else — see storage in GET /api/v1/{user}/status.

No confirmation code: nothing staged has ever been on the site and nobody has read it. A photograph already filed into a day is a different route, and that one does ask. The file and its sidecar go together.

The kinds of data this instance can read, and who wrote each format it understands: gps, costs. A kind is what the data is — a location history, a bank statement — and a format is who wrote it.

This is the only GET in the import feature, and it describes the door rather than what is behind it. Nothing anywhere hands back a position. A location history is every address somebody sleeps at and every place they work; what a reader ever sees is the derived line for one trip, drawn behind that trip's own gate.

The two kinds end differently. gps is stored as it is read — a coordinate is a measurement and there is nothing to decide about it. costs writes nothing at all: a statement covers the trip and the fortnight either side of it, and what each line was for is an editorial decision. It reports, a person agrees, and POST /api/v1/{user}/trips/{trip}/costs/import writes.

A trip-scoped token is refused on all of these — the history belongs to the journal, not to the trip you came on.

Takes a file somebody exported from somewhere else — Google Maps Timeline, a Takeout Records.json, a GPX track, plain JSON Lines from a tool of your own, or a Revolut statement — and reads it into the journal.

Say the kind. With two of them an absent one is refused rather than guessed at: reading a bank statement as positions, or a location history as money, is not a mistake to make quietly.

Three ways to hand over the bytes. inbox names a file already staged with POST /api/v1/{user}/inbox and is the normal path for a real export; multipart file is a one-shot; text is for a handful of lines pasted in. The import leaves the staged file where it is — deleting it is DELETE /api/v1/{user}/inbox/{id}, and worth doing, because it is the unthinned original.

Leave format out and the file is recognised from its contents. Name one only when detection gets it wrong, or when you wrote the importer.

Positions are thinned on the way in — one kept per five minutes or 250 metres, whichever comes first — so importing the same export twice changes nothing, and importing overlapping exports does not double anything.

Nothing is drawn by this call. POST /api/v1/{user}/trips/{trip}/track is what turns what is now stored into one trip's line.

The second half of a costs import. POST /api/v1/{user}/import read the statement and wrote nothing; this takes back the rows a person has agreed and records them as costs on the days.

Two decisions happen in between, and neither is yours. Which rows — a statement covers the trip, the rent and the phone bill. Which category — a statement says what was paid, never what it was for. Agree them against the import's merchants list, which is sorted biggest first because one decision about a merchant covers every payment to it. other is a real answer; a guess dressed as a category is not.

It adds, and never replaces. Costs somebody wrote by hand stay. Sending the same rows twice writes them twice — visible on the day and correctable there, which is the honest behaviour for an append.

A date whose day has not been written yet is reported back in orphaned and nothing is recorded for it. The cost is never moved to a neighbouring day.

Writable by anybody who may write the trip, trip-scoped tokens included: nothing here reads the owner's statement or reaches outside this trip.

Derives the ground actually covered on this trip and writes it into the trip, where the map draws it faintly under the day markers.

Four things happen, and three are about what does not come out: the line is clipped to the trip's dates (everything outside is the rest of somebody's life), the owner's private zones are cut out and the line broken there, a gap of more than two hours is left as a gap rather than joined — a flight is a hole in the data, not a straight line across a continent — and the rest is simplified to a few thousand points.

Answers with counts and never with a coordinate. Safe to run again whenever more history has been imported; it rewrites one file. A trip with nothing stored for its dates writes nothing and leaves any existing line alone.

Owner only, and a trip-scoped token is refused even for its own trip: deriving reads the owner's whole history across those dates.

The files are put into the day's entry for you. There is nothing to paste, and it does not matter whether you write the day before or after sending its pictures — only that the day exists.

Two ways in. multipart/form-data carries the bytes: day is the slug of a day in this trip, and files may repeat. application/json carries urls for this server to fetch — https only, public hosts only, refused after a redirect to a private address.

Two files are kept for each one sent: a resized copy for the browser and the original for print. Send the largest you have — for a URL upload the original is whatever the remote host served, so a 2000px source is what a photobook will be printed from, and there is no way to get the pixels back later.

The whole request may carry 512 MB, which is a different limit from the per-file one and is the one a batch of phone originals meets first. Over it the answer is 413 body_too_large, naming the cap and what arrived; nothing is written, and a day may be filled by as many calls as you like.

This route could put photographs on and never take one off, so the only remedy for a duplicate or a wrong upload was a shell on the server — B605. src — one or more — has to be exactly what GET .../days/<slug> handed back for this day; a name the day does not carry refuses the whole call rather than removing the rest and leaving you to notice which one silently did not land.

The files are actually deleted: the derivative, the poster if it was a clip, and the kept original — not merely detached from the day. A photobook or postcard order that already named one of these files is untouched; both resolve the photograph live, at send or print time, so deleting one a pending order names will make that order fail the same way it would if you had deleted the file by hand. A completed order already has its copy at the printer and is not affected either way.

The first call an agent makes when the owner pasted a prompt instead of reading out a code. Send the handover credential as Authorization: Bearer. It lasts 20 minutes, is spent by succeeding here, and is refused on every other route. A 401 means expired or already used — ask the person for a fresh one rather than retrying. The answer carries the 7-day token and the status URL to read next.

What the owner's own access page calls so it can print a pasteable prompt. Owner only, cookie or bearer. The credential it answers with lasts 20 minutes and can only be exchanged at POST /api/auth/handover — never used to read or write. An agent has no reason to call this; it is here so the contract is complete.

Public and unauthenticated. Read it before you do anything expensive: capabilities says which optional features are on and, when one is off, why — so an agent can tell "this server cannot send mail" from "this call was wrong". media says what an upload may be, which is the one limit worth knowing before rather than after sending 60 MB of photographs. status is error and the code 503 when the config or the content root is unreadable.

The whole list at once, not a merge: send everyone who is on the trip, including the ones already there. It is the byline and it is write access — everyone named may write to the trip and may hold a token scoped to it — so this is owner-only and a trip-scoped token cannot widen its own reach.

The whole list at once. Cosmetic — it changes the walking figures and nothing about who may read or write anything, which is why it is not owner-only the way people is. Ask …/travellers/presets for the vocabulary first; an unknown key inside a figure is refused rather than dropped.

Open, because it describes nothing about anybody: it is the list of hair, skin, clothing and pack values a figure may use, and twelve worked starting points. Read it before writing a travellers block rather than guessing at value names.

Answers SVG, not JSON. Give it figure (one figure as JSON) or party (a list), and optionally size in pixels. Nothing is stored. This is the call that makes "is this you?" a question somebody can answer.

The owner gets one row per live credential in the journal, each with email. Anybody else who has proved an address — a guest cookie, a year-long identity, or a trip-scoped bearer token — gets only the rows issued to that address, with no email field (the list is already implicitly theirs). There is no parameter that widens this: the filter is the caller's own proven address, never anything the request sends. Every row carries scope, in tripWriteScope's vocabulary, so a trip-bound key can be told apart from a journal-wide one.

{"revoke": "<key id>"}, with an id from the GET above. It ends that credential immediately — the way to answer "an agent has a token I want back". An id that is not this journal's, or — for a non-owner — not this caller's own row, answers the same 404 as an id that does not exist at all, so a guess learns nothing.

The narrow door for the two channels a published day can go out on. The wider one is PATCH …/config with features; this exists so a person can say "stop mailing me" without a call that could change anything else.

Per day, in the journal's languages, so a person can choose rather than have an agent write one. trip is required.

Nothing is bought and nothing is granted. It records a pending payment, mails the owner, and answers with paymentUrl — an absolute link to the page where a person chooses how to pay. The money and the credits happen there and at the payment provider, deliberately, so that no token can spend anything. Hand the URL over and report it as a request, never as a purchase.

tier is one of the fixed tiers; the response repeats credits and priceRappen so you can quote what was started. Owner-only.

What is used, what is allowed, what is left, and a breakdown — one row per trip, plus the inbox, the generated photobooks and postcards, and everything else. The rows sum to usedBytes exactly.

reclaimable is what a cleanup would take back without touching a photograph: generated PDFs and postcard sheets. Only the owner, in their own browser, can run one — report the number and let them decide.

Spends 50 credits and raises this journal's storage ceiling by 5 GB, immediately and for good — unlike /credits/purchase, this one really does charge. It cannot be undone, it does not expire, and buying twice adds twice. No request body: there is one thing to buy and one price.

The owner's own browser session, and nothing else. A bearer token is refused here whatever it is scoped to, the same way ordering a photobook or posting a card is: an agent that has just been refused an upload reports that the journal is full and lets the owner decide whether to delete something or buy more room. GET /api/v1/{user}/status is where the bytes held and the bytes allowed are read back.

The plan behind the confirmation the owner reads: bytes and file counts, split into photobooks, postcards and staged documents. ?staged=1 includes the documents in inbox/files/. Nothing is deleted.

Deletes files. Generated photobook PDFs for orders that finished printing, and dry-run postcard sheets. ?staged=1 also removes the documents staged in inbox/files/; staged photographs are never in scope, and are removed one at a time through DELETE /api/v1/{user}/inbox/{id} where a person is looking at what they are removing.

Nothing else is touched: every photograph, day and trip stays, and a printed book keeps its record, its price and its date — only the PDF goes, and it can be built again from photographs that are still there. A book still building is never touched.

The owner's own browser session, and never a token, for the same reason as buying storage: an agent reports what is taking the space and does not decide which of somebody's files to delete.

Authenticated by the payment id in the path, which is an unguessable capability reached from a link in the owner's own mail — not by a session and not by a token in the body. It adds no credits on any path; creditsAdded is zero and always will be.

What it does depends on whether this instance has a payment provider configured (/api/health says, under capabilities.credits.note). With one, the response carries url — a hosted checkout page to send the buyer to — and method in the request is ignored, because the provider's own page is where TWINT, a wallet or a card is chosen. Without one, it files a request and mails the instance operator an approval link; approver is the address it went to, and method is then required.

Authenticated by the single-use token in the body. It is reached from a link in the operator's mail rather than by anything an agent holds, and it is one of only two HTTP paths that add credits to a journal — the other is the payment provider's own signed webhook, which no client calls.

The first call to make, and the cheapest credential check there is: 401 means go and get a code, 200 means you are in. Carries the journal, the drafts waiting for a person to approve them — each with the call that publishes it — the trips this token may write to, which capabilities are on for this journal and why any is off, and a next saying what to do.

features here is deliberately only the four an agent can act on — mail, push, postcards, photobook — plus credits where this server bills. It is not the journal's whole capability list, and a name missing from it is not a name that is off: GET .../config carries all of them and /api/health says what this server can offer at all. The two fields share a name and answer different questions, which has misled a reader of this document before.

scope says whether you are holding the whole journal or one trip's slice; do not report a slice as the journal's total.

credits is here when this server charges for sends (B366): balance, and what each channel costs. Read it before publishing with send_mail or send_whatsapp — a balance too small refuses the whole publish with 402 and writes nothing. Absent means this server does not bill, not that the account is empty; it is also absent for a trip-scoped token, which can neither publish nor send.

storage is how full the journal is — usedBytes, limitBytes, remainingBytes and purchasedBytes. Read it before uploading a batch: a batch that would go past limitBytes is refused whole and nothing is written. It counts every byte under the journal's folder, photobook PDFs included, not only its photographs. A limitBytes of null means this instance sets no ceiling — never that the answer is unknown. Present for a trip-scoped token too, because the whole journal's ceiling is what refuses a trip's photographs. POST /api/v1/{user}/storage is how the owner raises it.

inbox counts what is staged and belongs to no day yet (B663), with the call that lists it. A non-zero count is the first thing to act on for a trip somebody has just come back from — the photographs are already here. Absent for a trip-scoped token, which the inbox route refuses.

malformed names a trip on disk with a trip.md too broken to parse (B83) — the same list GET .../trips carries, so writing a trip and reading this back cannot disagree about whether it took. next puts fixing one ahead of the draft queue: a broken file is a thing you may have just caused and can fix yourself, where the drafts are a person's decision. Present for an owner token only — a trip-scoped token learns nothing about the rest of the journal, malformed or not — and absent entirely when there is nothing broken.

Each draft carries where to publish it, and test: true if it is content nobody lived — including a day that inherits the flag from its trip and says nothing itself. Read that out with the rest: this is the list somebody is looking at when they decide what goes on the site (B134). Absent means real.

Send only what you are changing: {"features": {"contacts": true}}, or one or more of title, tagline, visibility, startLocation, units, locales, defaultLocale, displayCurrencies, manualRates, ownerTel. Before this there was no endpoint, tool or page that wrote a journal's config at all, so it was fixed at creation and only an operator with a shell could change it — which left journals unable to invite anybody (B182) and a title typoed at signup permanent (B220).

Capabilities can only ask for what the server already provides: the server's own config is a ceiling, and asking to exceed it is refused with the reason rather than written and silently ignored. Switching a capability off always works, except for the four the server decides alone: photobook and postcards cost the operator money at a printer, and logging and credits are the instance's own. All four are whatever the server says for every journal on it, and either direction is refused with capability_not_yours.

Capabilities and the rest are two calls. A body naming features alongside another field is 400 mixed_change and writes nothing: each call rewrites config.json whole, reads it back, and restores the previous bytes if it does not load, so a request doing that twice is one that can succeed halfway.

Three keys are never writable, each with its own reason in the refusal. The owner block is not writable as a whole, and owner.email in particular never is: it decides who can obtain a token for this journal, so a token must not be able to move it. The telephone number inside it is the exception, reached as the flat field ownerTel. baseCurrency is not a display setting — a cost written without a currency IS a cost in the base currency, so changing it re-reads every amount already recorded rather than reconverting it. media is the operator's, and the server's limits are already a ceiling over it. Owner only.

Any day, in any trip. The content is markdown, so this is the source rather than a conversion of it, and it is gated exactly like the HTML page — a private trip answers 404 here too. This is the .md twin of the day's own URL, and the form to use when you have a trip id: the search index identifies entries as {trip}/{slug}.

The short form, mirroring /{user}/day/{slug} — the current trip's day pages. If the current trip has no such slug, the journal's other readable trips are searched before this gives up, so a slug alone usually resolves.