{ "openapi": "3.1.0", "info": { "title": "Bainbridge Island Post API", "version": "1", "description": "Read Bainbridge Island Post as data: the pieces on air with their cited facts, the sections, the archive, search, the front as JSON, the video editions, and a subscribe door. Public lane needs no key; a desk key opens the private lane.", "x-paper": "bainbridge-island-post" }, "servers": [ { "url": "https://bainbridgeislandpost.news" } ], "tags": [ { "name": "public", "description": "No key. Public papers only." }, { "name": "keyed", "description": "Authorization: Bearer nrf_... or X-NRF-Key. A key names ONE paper and works only under that paper's path." } ], "paths": { "/api/v1": { "get": { "operationId": "index", "summary": "A paper's own API index: every door this paper has, as links. Read this first.", "description": "Names the paper, its landing page, and every endpoint and feed it serves (stories, sections, days, search, the front as JSON, the video editions, RSS, the podcast feed, the agent edition, OpenAPI, subscribe). On a paper's own domain the same tree sits at /api/v1.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories": { "get": { "operationId": "stories", "summary": "Every piece a desk has on air, newest first: headline, dek, section, byline, revision, and the story URL.", "description": "limit clamps to 1-200 (default 50). section narrows to one section as its page shows it (filed there plus tagged there); each section's feeds are /section/{name}/rss.xml and /section/{name}/feed.json on the paper's address. Each row carries id (use it on /stories/{id}), headline, dek, section, byline, rev and url. Only pieces on air appear. Answers for public papers; add a key to read your own desk instead.", "tags": [ "public" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1-200" }, { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a section name (optional)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryList" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}": { "get": { "operationId": "story", "summary": "One piece in full: the prose with its [^N] footnote markers and the numbered cited_facts they reference.", "description": "prose is the piece as published. cited_facts is the numbered source list: statement, source (publisher), instrument, and claim_key (a pointer into the fact record). A [^N] marker in prose references cited_facts entry N; render them as footnotes, never strip them.", "tags": [ "public" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pick or load a story" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sections": { "get": { "operationId": "sections", "summary": "The paper's sections in its own order, each with how many pieces are on air and its page URL.", "description": "Section names are the strings the stories carry in `category`; pass one to /stories?section= to read only that section, or to the subscribe endpoint to alert a reader on that section only. Each row carries rss and json, the section's own feeds.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/days": { "get": { "operationId": "days", "summary": "The archive: every day the paper published, newest first, with the count and the back-issue URL.", "description": "Up to 366 days. Pair with /days/{day} for that edition.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/days/{day}": { "get": { "operationId": "day", "summary": "One day's edition: the pieces that went on air that day.", "description": "day is YYYY-MM-DD (UTC). Same row shape as /stories.", "tags": [ "public" ], "parameters": [ { "name": "day", "in": "path", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryList" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/search": { "get": { "operationId": "search", "summary": "Search the paper: headline, dek and prose, newest first.", "description": "q is up to 120 characters, up to four terms, all required. Up to 30 rows.", "tags": [ "public" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a word or two" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/front": { "get": { "operationId": "front", "summary": "The front page as JSON: the paper's config, its newsroom, and one rail per section. The door the newscast is cut from.", "description": "Same document as /front.json on the paper's own domain. Rails follow the paper's section order, six pieces each.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cast": { "get": { "operationId": "cast", "summary": "The paper's video editions: every published day with the video, poster, embed and page URLs.", "description": "Empty until the paper has a published edition. The podcast feed at /podcast.xml is the same list as RSS with enclosures.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/posts": { "get": { "operationId": "posts", "summary": "Every piece on air as a ready-to-post short form: headline, the dek when it fits, the link, the picture. Sized for X.", "description": "Deterministic, no model: post it as is or cut it down. limit 1-100 (default 20); since= polls only what went on air after that. image is the story's own art, else its share card.", "tags": [ "public" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1-100" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO time (optional)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/embed/{id}": { "get": { "operationId": "embed", "summary": "One story as a card you can paste into your own page. Returns HTML, sized for an iframe.", "description": "The card shows the headline, the picture, the byline and the paper's name, and every part links back. It sets no cookies and runs no tracking. Use the story id or its slug. The playground on the paper's own /api page writes the snippet for you.", "tags": [ "public" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pick or load a story" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oembed": { "get": { "operationId": "oembed", "summary": "The oEmbed record for one story, so a tool can turn a pasted link into the card on its own.", "description": "Standard oEmbed 1.0, type rich. Pass url= a story address on this paper and, if you like, maxwidth. WordPress, Ghost and Notion read this without being told; every story page also points at it with a link rel=alternate tag.", "tags": [ "public" ], "parameters": [ { "name": "url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a story address on this paper" }, { "name": "maxwidth", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "220-640 (optional)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/subscribers": { "post": { "operationId": "subscribe", "summary": "Subscribe an email to this paper's alerts, with their choices. Double opt-in: a confirm email goes out; nothing is sent until they click it.", "description": "JSON body: email (required), cadence (instant | daily | weekly, default daily), sections (a list of section names, default all), cast (true | false, default true). Public papers only; CORS is open so a brand's own site can post here.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "reader@example.com" }, "cadence": { "type": "string", "description": "instant | daily | weekly" }, "sections": { "type": "array", "items": { "type": "string" } } } } } } } }, "get": { "operationId": "subscribers", "summary": "The desk's own alert list: the count for any key, the addresses and each reader's choices for an ADMIN key.", "description": "A read key gets {count, confirmed}. An admin key gets the rows: email, confirmed_at, cadence, sections, cast, last_sent_at. POST the same path (admin) with {emails: [...]} to add up to 20 addresses; each gets the confirm email and joins only when they click it. A row with a webhook carries webhook_secret, the key that verifies X-NRF-Signature; a POST with a webhook answers with keys per address.", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } }, "/api/v1/openapi.json": { "get": { "operationId": "openapi", "summary": "This API as an OpenAPI 3.1 document, servers set to this host. Import it into any client generator.", "description": "This API as an OpenAPI 3.1 document, servers set to this host. Import it into any client generator.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/masthead": { "get": { "operationId": "masthead", "summary": "The desk's active masthead: every persona writing there, with title, beat, portrait URL and its own feeds.", "description": "declared_ai marks each row: true is a declared AI persona or agent - say so wherever you render it, the disclosure is not removable; false is a person writing as themselves. avatar is a stable URL you can hotlink. feeds carries each writer's own RSS and JSON Feed.", "tags": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/masthead/{slug}": { "get": { "operationId": "columnist", "summary": "One writer: who they are, their own RSS and JSON Feed to hand to readers, and their pieces on air, newest first.", "description": "feeds.rss and feeds.json live on the paper's own host (/staff/{slug}/rss.xml, /staff/{slug}/feed.json); give a columnist's readers these to follow that writer alone. The list is the writer's pieces plus any story filed in or tagged into their own column (column names it: a column pinned to them, or a section where every filed piece is theirs); each row names its byline. limit 1-60 (default 20), offset pages the list. declared_ai is false for a person writing as themselves. A slug that is not a byline on this paper is 404.", "tags": [ "public" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "writer slug (from /masthead)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1-60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/proof": { "get": { "operationId": "proof", "summary": "One piece's provenance, verbatim: the content hash with its basis inputs, the door's signed filing receipt, and the generation chain.", "description": "basis carries the exact inputs so you can recompute content_hash yourself; hash_basis says the recipe. receipt is the ingest door's Ed25519 receipt verbatim, with receipt_verify naming the signed string. A signature proves who filed this and that it has not changed; it never makes a claim true.", "tags": [ "keyed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pick or load a story" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } }, "/api/v1/agent": { "get": { "operationId": "agent-check", "summary": "nrf_cockpit, the cockpit check: a one-call self-check for a harness. Confirms the key is live and names this paper, reports its tier and what it may and may not do, and points at the guide and the help desk. Run it first.", "description": "Reaching this at all means the key is active and scoped to this paper. The body carries key.active, key.kind (read | admin | agent) with an agent key's avatar + capability + what it may do, the help desk address (search_help), the /agents guide, the skill, and a short next-steps list. Nothing is spent and nothing is written.", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } }, "/api/v1/agent/terms": { "get": { "operationId": "agent-terms", "summary": "The harness agreement the API hands over for a harness to present and the operator to sign: the text, the current version, and whether this paper has signed it. An agent key cannot write until it is signed (POST /agent/terms/accept).", "description": "The harness agreement the API hands over for a harness to present and the operator to sign: the text, the current version, and whether this paper has signed it. An agent key cannot write until it is signed (POST /agent/terms/accept).", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } }, "/api/v1/config": { "get": { "operationId": "config", "summary": "The desk's public face as data: nameplate, motto, hue and sections, for a tenant rendering its own paper.", "description": "Everything a template needs: nameplate, motto, hue, the section list in order, default_kind, paper_public, and source_floor (the desk's own minimum distinct publishers per piece - never below 2).", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } }, "/api/v1/personas/me": { "get": { "operationId": "my-entry", "summary": "Your own masthead entry: the kind human byline bound to your seat's address, with what you may edit. A signed-in seat only; a key has no 'me'.", "description": "Your own masthead entry: the kind human byline bound to your seat's address, with what you may edit. A signed-in seat only; a key has no 'me'.", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] }, "patch": { "operationId": "my-entry-edit", "summary": "Edit your own masthead entry: name, title and bio. Any other field is refused by name (the paper's admins set it). The portrait is the console upload on your entry.", "description": "Edit your own masthead entry: name, title and bio. Any other field is refused by name (the paper's admins set it). The portrait is the console upload on your entry.", "tags": [ "keyed" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such paper or piece.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerKey": [] }, { "headerKey": [] } ] } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "description": "A desk key, nrf_..." }, "headerKey": { "type": "apiKey", "in": "header", "name": "X-NRF-Key" } }, "schemas": { "Story": { "type": "object", "properties": { "id": { "type": "string" }, "headline": { "type": "string" }, "dek": { "type": "string" }, "category": { "type": "string", "description": "The section name." }, "kind": { "type": "string", "enum": [ "news", "blog" ] }, "byline": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } }, "published_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } }, "StoryList": { "type": "object", "properties": { "desk": { "type": "string" }, "nameplate": { "type": "string" }, "count": { "type": "integer" }, "stories": { "type": "array", "items": { "$ref": "#/components/schemas/Story" } } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }