{
  "openapi": "3.1.0",
  "info": {
    "title": "blygd API",
    "version": "0.4.0",
    "description": "The write and reading API of blygd, a Blygger studio (protocol 0.4). It is studio-private, not protocol (§16.6): the public surface is each origin's static files. Spec references (§) are to blygger-spec docs/protocol-v0.4.md.\n\nEvery HTML string that came from another origin is returned verbatim; clients MUST sanitize it before rendering (§14). Responses that carry imported bytes include a notice saying so.\n\nAuthenticate with a bearer token; the one operation that takes none, redeeming an invite, is how someone without one gets one. Each operation's security requirement names the one scope it needs; the owner token `*` holds every scope.\n\nCross-origin clients: every response carries `Access-Control-Allow-Origin: *` and exposes `Retry-After` and `WWW-Authenticate`, and preflights are answered for any path here (methods GET, POST, PUT, PATCH, DELETE; headers Authorization and Content-Type; cached two hours). The bearer token is the only credential: no cookie is ever read, and no response allows credentials. Preflights are not budgeted.\n\nFinding the blyg: this host has no directory of blygs, and nothing is served at its root. Each blyg is mounted at its own path, `https://host/~{handle}/` (a blyg made before the `~` namespace keeps `https://host/{handle}/`). `GET /api/me` returns the caller's `origin`, that base URL, and every public file (`blyg.json`, `feed.xml`, `items/index.json`, `items/{id}.json`) is relative to it.\n\nRequests are budgeted per token and per user (a user's budget is twice a token's, across all their tokens), and an operation that takes no token per address. Each operation's `x-blygd-cost` names its class: `default` (120 a minute, bursts of 60), `fetch` (12 a minute; the call fetches from other hosts), `export` (2 a minute), `upload` (30 a minute, bursts of 20) and `stream` (no per-request budget; at most 8 open streams). Over budget is a 429 with `Retry-After`. An address that presents a wrong token too often is refused for a while, whatever token it then sends; a request with no `Authorization` header is not counted."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "meta"
    },
    {
      "name": "origin"
    },
    {
      "name": "items"
    },
    {
      "name": "media"
    },
    {
      "name": "hoppers"
    },
    {
      "name": "mentions"
    },
    {
      "name": "reader"
    },
    {
      "name": "tokens"
    },
    {
      "name": "invites"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/api/openapi.json": {
      "get": {
        "operationId": "getOpenAPI",
        "tags": [
          "meta"
        ],
        "summary": "This document.",
        "security": [],
        "responses": {
          "200": {
            "description": "The OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "meta"
        ],
        "summary": "The calling token's user, scopes and origin.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "operationId": "streamEvents",
        "tags": [
          "meta"
        ],
        "summary": "A Server-Sent Events stream of change hints for this user.",
        "description": "Each event names what changed, never the state: re-fetch what you show. Events, by type:\n\n- `import` (needs reader:read): a poll of one of your subscriptions finished. `{subscription_id, items, more, error?}`, where `more` means a backfill continues with the next batch in about a minute.\n- `subscribe` (needs reader:read): an entry of one of your subscription imports was tried. `{id, status, subscription_id?, error?}`, where status is subscribed, failed, or pending when it will be tried again.\n- `item` (needs items:read): one of your items changed, from any client. `{id, change, version?, draft_rev?}`, where change is created, edited, deleted, published, withdrawn or pinned; version is the one published, withdrawn or pinned; and draft_rev is the draft's revision after a create, edit or publish, so a client can tell its own change from another's.\n- `mention` (needs mentions:read): an inbound mention to your origin arrived or changed. `{id, status, relation?}`.\n- `outbound` (needs mentions:read): one of your outbound mentions was attempted. `{id, status, last_result}`.\n\nA heartbeat comment arrives every 25 s. The stream ends within one heartbeat once its token is revoked or expires, and a reconnect then answers 401: sign in again rather than retry. Events missed while disconnected are not replayed; fetch state on reconnect. Browsers should read this with fetch(), which can send the Authorization header; EventSource cannot. At most 8 streams per user.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-blygd-cost": "stream",
        "responses": {
          "200": {
            "description": "The stream, until the client disconnects.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Too many open streams for this user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Events are not running.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/origin": {
      "get": {
        "operationId": "getOrigin",
        "tags": [
          "origin"
        ],
        "summary": "Origin settings.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Origin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "patchOrigin",
        "tags": [
          "origin"
        ],
        "summary": "Change origin settings and re-render the surface.",
        "security": [
          {
            "bearer": [
              "origin:write"
            ]
          }
        ],
        "x-blygd-cost": "upload",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Origin"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OriginPatch"
              }
            }
          }
        }
      }
    },
    "/api/origin/export": {
      "get": {
        "operationId": "exportOrigin",
        "tags": [
          "origin"
        ],
        "summary": "The origin as a static deployment: a gzipped tar.",
        "description": "Every surface file at its origin-relative path, with directory pages (the feed page, permalink pages, pinned version pages) as `index.html`, plus every media file a published version references. Serve it at the origin's base URL: every URL inside is absolute against it. A static deployment advertises no Webmention endpoint (§15.1, §15.7), so the export is rendered with mentions off: no manifest `webmention` key and no `rel=\"webmention\"` links, whatever the origin's setting. Pins are their stored bytes. Nothing is written. Drafts, hopper pages and the webmention endpoint are not part of it.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "export",
        "responses": {
          "200": {
            "description": "The archive, as `blyg-YYYYMMDD.tar.gz`.",
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/items": {
      "get": {
        "operationId": "listItems",
        "tags": [
          "items"
        ],
        "summary": "List own items, newest activity first.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "published",
                "withdrawn"
              ]
            },
            "description": "Filter by state."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            },
            "description": "Default 100."
          }
        ]
      },
      "post": {
        "operationId": "createItem",
        "tags": [
          "items"
        ],
        "summary": "Create a draft: a fragment, a thread, a stub (stub_of), or a fork (forked_from).",
        "security": [
          {
            "bearer": [
              "items:write"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "A fork without content_md fetches the pinned source (or reads it, if it is your own) and flattens it into the draft (§5.6 rule 6).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemCreate"
              }
            }
          }
        }
      }
    },
    "/api/items/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ItemID"
        }
      ],
      "get": {
        "operationId": "getItem",
        "tags": [
          "items"
        ],
        "summary": "An item with every published version.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "patchItem",
        "tags": [
          "items"
        ],
        "summary": "Edit the draft, the next note, or generation metadata.",
        "security": [
          {
            "bearer": [
              "items:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "Nothing changes on the wire until the next publish. With draft_rev, the edit applies only to the draft at that revision (409 stale otherwise), so two clients cannot overwrite each other unseen.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemPatch"
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteItem",
        "tags": [
          "items"
        ],
        "summary": "Hard-delete a never-published draft.",
        "security": [
          {
            "bearer": [
              "items:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/items/{id}/preview": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ItemID"
        }
      ],
      "post": {
        "operationId": "previewItem",
        "tags": [
          "items"
        ],
        "summary": "Compose the draft as publishing it now would, and store nothing.",
        "description": "Composes the draft, or content_md in its place (an edit not yet saved), exactly as POST /api/items/{id}/publish would now: [TK] scopes stripped, [[id]] links resolved, and a thread's quotes baked from the versions they would quote, yours first, then your subscriptions' imports (§10.2). Nothing is stored, rendered to your surface, or sent. Every reason a publish would be refused is listed in problems, not returned as an error, and a directive that cannot bake is marked where it stands. It does not check a fork's pin at its origin, which only publishing fetches. Imports change as polls land, so a publish later may bake newer versions than this showed.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preview"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/items/{id}/publish": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ItemID"
        }
      ],
      "post": {
        "operationId": "publishItem",
        "tags": [
          "items"
        ],
        "summary": "Publish the draft as the next version.",
        "security": [
          {
            "bearer": [
              "items:publish"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "Directives and [[id]] links resolve now: own items first, then your subscriptions' imports (§10.2). Every unresolvable one is listed in a 422's problems. 409 when nothing changed. 409 stale when draft_rev is sent and the draft has moved on, or when the draft changes while publishing.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublishRequest"
              }
            }
          }
        }
      }
    },
    "/api/items/{id}/withdraw": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ItemID"
        }
      ],
      "post": {
        "operationId": "withdrawItem",
        "tags": [
          "items"
        ],
        "summary": "Publish a withdrawal endcap (§9).",
        "security": [
          {
            "bearer": [
              "items:withdraw"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoteRequest"
              }
            }
          }
        }
      }
    },
    "/api/items/{id}/versions/{n}/pin": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ItemID"
        },
        {
          "$ref": "#/components/parameters/VersionN"
        }
      ],
      "post": {
        "operationId": "pinVersion",
        "tags": [
          "items"
        ],
        "summary": "Pin a version: irrevocable (§8).",
        "security": [
          {
            "bearer": [
              "items:pin"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PinResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/hoppers": {
      "get": {
        "operationId": "listHoppers",
        "tags": [
          "hoppers"
        ],
        "summary": "List hoppers.",
        "security": [
          {
            "bearer": [
              "hoppers:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HopperList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "createHopper",
        "tags": [
          "hoppers"
        ],
        "summary": "Create a hopper.",
        "security": [
          {
            "bearer": [
              "hoppers:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Hopper"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HopperName"
              }
            }
          }
        }
      }
    },
    "/api/hoppers/{hid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/HopperID"
        }
      ],
      "get": {
        "operationId": "getHopper",
        "tags": [
          "hoppers"
        ],
        "summary": "A hopper and its members.",
        "security": [
          {
            "bearer": [
              "hoppers:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HopperDetail"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "renameHopper",
        "tags": [
          "hoppers"
        ],
        "summary": "Rename a hopper, or make it public or private.",
        "description": "A public hopper is shown at {origin}h/{slug}/ and named in the manifest's hoppers list with its live RSS feed, {origin}h/{slug}/feed.xml (§6.1, §13.5). Making one public or private also needs origin:write; renaming a public one renames its manifest entry.",
        "security": [
          {
            "bearer": [
              "hoppers:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Hopper"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HopperPatch"
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteHopper",
        "tags": [
          "hoppers"
        ],
        "summary": "Delete a hopper.",
        "security": [
          {
            "bearer": [
              "hoppers:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/hoppers/{hid}/members": {
      "parameters": [
        {
          "$ref": "#/components/parameters/HopperID"
        }
      ],
      "post": {
        "operationId": "addMember",
        "tags": [
          "hoppers"
        ],
        "summary": "Add a reference to an own or imported item.",
        "security": [
          {
            "bearer": [
              "hoppers:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Created"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberCreate"
              }
            }
          }
        }
      }
    },
    "/api/hoppers/{hid}/members/{mid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/HopperID"
        },
        {
          "$ref": "#/components/parameters/MemberID"
        }
      ],
      "delete": {
        "operationId": "removeMember",
        "tags": [
          "hoppers"
        ],
        "summary": "Remove a member.",
        "security": [
          {
            "bearer": [
              "hoppers:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/media": {
      "get": {
        "operationId": "listMedia",
        "tags": [
          "media"
        ],
        "summary": "List uploaded media, newest first.",
        "security": [
          {
            "bearer": [
              "items:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "uploadMedia",
        "tags": [
          "media"
        ],
        "summary": "Upload an image: the raw bytes as the body, typed by Content-Type.",
        "security": [
          {
            "bearer": [
              "items:write"
            ]
          }
        ],
        "x-blygd-cost": "upload",
        "responses": {
          "201": {
            "description": "Stored, or already stored: the same bytes are the same object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Media"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "The declared type must match the bytes. Reference it from markdown as media/… ; publish checks every reference exists, and lists them in the item's media array.",
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "contentMediaType": "image/png"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "contentMediaType": "image/jpeg"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "contentMediaType": "image/gif"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "contentMediaType": "image/webp"
              }
            }
          }
        }
      }
    },
    "/api/media/{file}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MediaFile"
        }
      ],
      "delete": {
        "operationId": "deleteMedia",
        "tags": [
          "media"
        ],
        "summary": "Delete media no published version references.",
        "security": [
          {
            "bearer": [
              "items:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/mentions": {
      "get": {
        "operationId": "listMentions",
        "tags": [
          "mentions"
        ],
        "summary": "Inbound Webmentions, newest first (at most 200).",
        "security": [
          {
            "bearer": [
              "mentions:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MentionList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "verified",
                "failed",
                "gone"
              ]
            },
            "description": "Filter by status."
          },
          {
            "name": "class",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "response",
                "notice"
              ]
            },
            "description": "Filter by class (§15.5): responses, or notices to hold apart."
          },
          {
            "name": "include_blocked",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            },
            "description": "Also list mentions from blocked sources."
          }
        ]
      }
    },
    "/api/mentions/{mid}/approval": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MentionID"
        }
      ],
      "put": {
        "operationId": "approveMention",
        "tags": [
          "mentions"
        ],
        "summary": "Show a verified mention on its target's page (§15.5).",
        "security": [
          {
            "bearer": [
              "mentions:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Shown."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "Publishing a response is curation, never automatic, so this also needs origin:write. What shows: a verb, the source's author name, its host and a link; no words from the source. A notice is refused with 409: it is never shown among responses (§15.5)."
      },
      "delete": {
        "operationId": "hideMention",
        "tags": [
          "mentions"
        ],
        "summary": "Take a mention off its target's page.",
        "security": [
          {
            "bearer": [
              "mentions:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Hidden."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/mention-blocks": {
      "get": {
        "operationId": "listMentionBlocks",
        "tags": [
          "mentions"
        ],
        "summary": "List blocked sources.",
        "security": [
          {
            "bearer": [
              "mentions:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "blockMentionSource",
        "tags": [
          "mentions"
        ],
        "summary": "Block a host or a whole registrable domain.",
        "security": [
          {
            "bearer": [
              "mentions:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "201": {
            "description": "Blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Block"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "Claims from a blocked source are answered like any other and dropped: nothing stored, nothing fetched. Mentions already received from it lose their approval at once.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlockCreate"
              }
            }
          }
        }
      }
    },
    "/api/mention-blocks/{bid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BlockID"
        }
      ],
      "delete": {
        "operationId": "unblockMentionSource",
        "tags": [
          "mentions"
        ],
        "summary": "Remove a block. Withdrawn approvals stay withdrawn.",
        "security": [
          {
            "bearer": [
              "mentions:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/outbound": {
      "get": {
        "operationId": "listOutbound",
        "tags": [
          "mentions"
        ],
        "summary": "Outbound Webmentions, most recently changed first (at most 200).",
        "security": [
          {
            "bearer": [
              "mentions:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutboundList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/subscriptions": {
      "get": {
        "operationId": "listSubscriptions",
        "tags": [
          "reader"
        ],
        "summary": "List subscriptions.",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "subscribe",
        "tags": [
          "reader"
        ],
        "summary": "Subscribe by any URL; resolution follows §12.1.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "description": "Resolution failed; trail lists the URLs tried.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/{sid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        }
      ],
      "get": {
        "operationId": "getSubscription",
        "tags": [
          "reader"
        ],
        "summary": "One subscription.",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "patchSubscription",
        "tags": [
          "reader"
        ],
        "summary": "Rename for yourself, or publish/withdraw a blogroll entry.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "description": "in_blogroll also needs origin:write (§11).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPatch"
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "unsubscribe",
        "tags": [
          "reader"
        ],
        "summary": "Unsubscribe; drops any blogroll entry for it.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/subscriptions/{sid}/resolve": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        }
      ],
      "post": {
        "operationId": "reresolveSubscription",
        "tags": [
          "reader"
        ],
        "summary": "Re-run resolution and report; changes nothing (§12.2).",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReresolveResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Resolution failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/{sid}/move": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        }
      ],
      "post": {
        "operationId": "moveSubscription",
        "tags": [
          "reader"
        ],
        "summary": "Move to a confirmed new identity (§12.2).",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MoveResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "description": "Resolution failed, or to resolves elsewhere.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string"
                  }
                },
                "required": [
                  "to"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/{sid}/poll": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        }
      ],
      "post": {
        "operationId": "pollSubscription",
        "tags": [
          "reader"
        ],
        "summary": "Poll this subscription now.",
        "description": "Within §12.3's etiquette: refused while the origin is backing off after failures, within a minute of its last poll (the mirror is shared by every subscriber), or while another poll of it runs. A refusal is 429 with Retry-After and retry_at.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "responses": {
          "200": {
            "description": "Polled; the subscription as it now stands.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Not now; see Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/subscriptions/imports": {
      "post": {
        "operationId": "importSubscriptions",
        "tags": [
          "reader"
        ],
        "summary": "Queue an OPML list of subscriptions.",
        "description": "Send an OPML document (a blogroll, §11, or another reader's export) as opml, or a url: an OPML file, or a blyg whose manifest names a blogroll (§6.1). Every entry with an http(s) xmlUrl, or an htmlUrl when it has none, is queued and resolved in the background like POST /api/subscriptions (§12.1), at most one per user at a time, so a long list costs no subscribe budget. A blyg's feed upgrades to the blyg itself (§11). Entries already queued or subscribed are left alone; failed ones are tried again. An entry's title becomes the subscription's display title when it differs from the origin's own and you have not named it. Imported subscriptions never join your blogroll (§11: inclusion is opt-in). Watch GET /api/subscriptions/imports, or the subscribe event.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "fetch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportResult"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "listImports",
        "tags": [
          "reader"
        ],
        "summary": "List queued subscription imports.",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "subscribed",
                "failed"
              ]
            },
            "description": "Only entries in this status."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "clearImports",
        "tags": [
          "reader"
        ],
        "summary": "Forget queued imports.",
        "description": "Forgets the entries in status, or all of them. No subscription changes, and a pending entry forgotten is never tried.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "subscribed",
                "failed"
              ]
            },
            "description": "Only entries in this status."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClearResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/reader/feed": {
      "get": {
        "operationId": "readerFeed",
        "tags": [
          "reader"
        ],
        "summary": "The merged reading feed (§13.7), keyset-paged.",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Cursor from a previous page's next."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            },
            "description": "Default 50."
          },
          {
            "name": "subscription",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Only this subscription."
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            },
            "description": "Only unread items."
          }
        ]
      }
    },
    "/api/reader/items/{sid}/{iid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        },
        {
          "$ref": "#/components/parameters/ImportedItemID"
        }
      ],
      "get": {
        "operationId": "readerItem",
        "tags": [
          "reader"
        ],
        "summary": "One imported item, with retained pins.",
        "security": [
          {
            "bearer": [
              "reader:read"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReaderItemResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/reader/items/{sid}/{iid}/read": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SubscriptionID"
        },
        {
          "$ref": "#/components/parameters/ImportedItemID"
        }
      ],
      "put": {
        "operationId": "markRead",
        "tags": [
          "reader"
        ],
        "summary": "Mark read at the current version.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "markUnread",
        "tags": [
          "reader"
        ],
        "summary": "Mark unread.",
        "description": "Unmarking an item that is already unread is not an error. An item the caller does not hold, through a subscription of their own, is a 404, as it is for marking it read.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/reader/read": {
      "post": {
        "operationId": "markAllRead",
        "tags": [
          "reader"
        ],
        "summary": "Mark read everything a feed could have shown.",
        "description": "Marks read, at its current version, every live item whose current version blygd first saw at or before as_of: everything a feed read at as_of could have shown, on every page. Send the as_of of the feed you showed. A version that arrives later stays unread, even one the origin dates earlier, which the feed sorts among items already read (§13.7). With subscription_id, only that subscription's items.",
        "security": [
          {
            "bearer": [
              "reader:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MarkAllRead"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarkAllReadResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/tokens": {
      "get": {
        "operationId": "listTokens",
        "tags": [
          "tokens"
        ],
        "summary": "List tokens.",
        "security": [
          {
            "bearer": [
              "tokens:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "mintToken",
        "tags": [
          "tokens"
        ],
        "summary": "Mint a token with a subset of your scopes.",
        "security": [
          {
            "bearer": [
              "tokens:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenMinted"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenMint"
              }
            }
          }
        },
        "description": "Mints a token holding a subset of the caller's scopes, expiring no later than the caller does: a minted token never outlives its minter. A device token that expires is replaced by minting from a token that outlives it, usually the owner's, which never expires and belongs offline. There is no refresh: a long-lived tokens:write token kept on the device would be that credential."
      }
    },
    "/api/tokens/self": {
      "delete": {
        "operationId": "revokeSelf",
        "tags": [
          "tokens"
        ],
        "summary": "Revoke the token making this request: sign out.",
        "description": "Any token may end itself. Revoking another token takes tokens:write.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Revoked; the token no longer authenticates."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/tokens/{tid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TokenID"
        }
      ],
      "delete": {
        "operationId": "revokeToken",
        "tags": [
          "tokens"
        ],
        "summary": "Revoke a token.",
        "security": [
          {
            "bearer": [
              "tokens:write"
            ]
          }
        ],
        "x-blygd-cost": "default",
        "responses": {
          "204": {
            "description": "Done."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/invites/redeem": {
      "post": {
        "operationId": "redeemInvite",
        "tags": [
          "invites"
        ],
        "summary": "Make a new user and blyg with an invite code.",
        "description": "Takes no token: the invite code is the credential. An operator mints codes with `blygd invite`; each makes one user. The new blyg is mounted at `https://host/~{handle}/`, and the handle is in its URL for good, as everything it publishes is (§4). The response carries the owner token (`*`, never expiring) once; trade it for a narrower, expiring token (POST /api/tokens) and keep it offline. A handle that is taken or malformed leaves the invite unused. Every refused code, unknown, used or expired, is the same 422, and counts as a failed authentication from this address, as a wrong token does; the cost class is charged to the address.",
        "security": [],
        "x-blygd-cost": "fetch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteRedeem"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteRedeemed"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Invalid"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A token minted by `blygd user add`, `blygd token mint`, POST /api/tokens, or, as an owner token, POST /api/invites/redeem. Scopes are listed per operation."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid",
              "not_found",
              "conflict",
              "stale",
              "forbidden",
              "unauthorized",
              "unresolved",
              "rate_limited",
              "too_soon",
              "too_many_streams",
              "too_large",
              "unavailable",
              "internal"
            ],
            "description": "Stable code. invalid: a malformed request (400) or one refused as it stands (422). not_found: 404. conflict: 409. stale: the draft changed since the draft_rev sent (409); read it again. forbidden: the token lacks the operation's scope (403). unauthorized: no token, or one unknown, revoked or expired (401). unresolved: a URL that did not resolve (422, with trail). rate_limited: over a request budget, or too many failed authentications from this address (429). too_soon: a poll refused by §12.3's etiquette (429, with retry_at). too_many_streams: at most 8 open event streams per user (429). too_large: media over the upload cap (413). unavailable: events are not running (503). internal: the server's fault (500)."
          },
          "message": {
            "type": "string"
          },
          "problems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Problem"
            },
            "description": "Every reason a draft cannot be published (§10.2), on a 422 from publish."
          },
          "trail": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "URLs tried, on a failed resolution (§12.1 step 6)."
          },
          "retry_at": {
            "type": "string",
            "format": "date-time",
            "description": "When a refused poll may run (429 from poll)."
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "Problem": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "description": "The directive, link or [TK] scope at fault, as written."
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "at",
          "reason"
        ],
        "additionalProperties": false
      },
      "Me": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "The caller's blyg base URL, `https://host/~{handle}/`, with a trailing slash. Public files such as `blyg.json` are relative to it."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this token stops authenticating; null never."
          }
        },
        "required": [
          "handle",
          "scopes",
          "origin",
          "expires_at"
        ],
        "additionalProperties": false
      },
      "Scope": {
        "type": "string",
        "enum": [
          "*",
          "items:read",
          "items:write",
          "items:publish",
          "items:withdraw",
          "items:pin",
          "hoppers:read",
          "hoppers:write",
          "mentions:read",
          "mentions:write",
          "origin:write",
          "tokens:write",
          "reader:read",
          "reader:write"
        ]
      },
      "Origin": {
        "type": "object",
        "properties": {
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "Identity origin (§12.2), ending in /."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "author": {
            "description": "Manifest author (§6.1), an object or null."
          },
          "byline": {
            "description": "Default per-item author (§5.5), an opaque object or null."
          },
          "accept_mentions": {
            "type": "boolean"
          }
        },
        "required": [
          "origin",
          "title",
          "description",
          "author",
          "byline",
          "accept_mentions"
        ],
        "additionalProperties": false
      },
      "OriginPatch": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "author": {
            "type": [
              "object",
              "null"
            ]
          },
          "byline": {
            "type": [
              "object",
              "null"
            ]
          },
          "accept_mentions": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "Selector": {
        "type": "object",
        "properties": {
          "exact": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "suffix": {
            "type": "string"
          }
        },
        "required": [
          "exact"
        ],
        "description": "W3C text-quote selector of a partial transclusion (§10.3).",
        "additionalProperties": false
      },
      "Cited": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "excerpt": {
            "type": "string",
            "maxLength": 200
          },
          "url": {
            "type": "string"
          },
          "retrieved": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "retrieved"
        ],
        "description": "The human half of a citation (§5.9): frozen, self-asserted, never verified.",
        "additionalProperties": false
      },
      "Reference": {
        "type": "object",
        "properties": {
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "Identity origin. Omitted in transclusions[] for own-origin sources (§10.3)."
          },
          "id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "selector": {
            "$ref": "#/components/schemas/Selector"
          },
          "cited": {
            "$ref": "#/components/schemas/Cited"
          }
        },
        "required": [
          "id",
          "version"
        ],
        "description": "The reference shape (§5.9).",
        "additionalProperties": false
      },
      "StubOf": {
        "description": "stub_of (§10.6): a blyg reference, or a plain-web {url}.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "origin": {
                "type": "string",
                "format": "uri"
              },
              "id": {
                "type": "string",
                "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
                "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
              },
              "version": {
                "type": "integer",
                "minimum": 1
              },
              "cited": {
                "$ref": "#/components/schemas/Cited"
              }
            },
            "required": [
              "origin",
              "id",
              "version"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "cited": {
                "$ref": "#/components/schemas/Cited"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          }
        ]
      },
      "StubTarget": {
        "description": "What a new stub responds to. By id, the studio resolves the target (own items first, then your subscriptions; give origin to choose) and freezes version and cited. By url, cited is yours; retrieved defaults to now and the excerpt is held to 200 characters.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
                "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
              },
              "origin": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "cited": {
                "$ref": "#/components/schemas/Cited"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          }
        ]
      },
      "GenSource": {
        "type": "object",
        "properties": {
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "Identity origin of another origin's item; omitted for an own item (§5.7 rule 1)."
          },
          "id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "cited": {
            "$ref": "#/components/schemas/Cited"
          }
        },
        "required": [
          "id",
          "version"
        ],
        "description": "A generation source (§5.7 rule 1): a reference to an item version the generator drew on. It resolves like a directive, so it may be another origin's item (rule 8).",
        "additionalProperties": false
      },
      "Generated": {
        "type": "object",
        "properties": {
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GenSource"
            }
          },
          "model": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "sources"
        ],
        "description": "One generated span's provenance (§5.7).",
        "additionalProperties": false
      },
      "GenMeta": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "What the client declares about one [TK] scope, by position.",
        "additionalProperties": false
      },
      "Version": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fragment",
              "thread",
              "withdrawn"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "note_generated": {
            "type": "boolean"
          },
          "content_md": {
            "type": "string"
          },
          "content_html": {
            "type": "string",
            "description": "For a thread, contains other origins' baked HTML verbatim (§10.2). Sanitize before rendering (§14)."
          },
          "content_hash": {
            "type": "string"
          },
          "author": {
            "description": "Arbitrary JSON, passed through verbatim."
          },
          "transclusions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reference"
            }
          },
          "stub_of": {
            "$ref": "#/components/schemas/StubOf"
          },
          "generated": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Generated"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "description": "One entry per resolved [[id]] link, in document order (§10.3a). Absent when the version has none, and on a withdrawal endcap."
          },
          "pinned_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "version",
          "kind",
          "at",
          "note",
          "note_generated",
          "content_md",
          "content_html",
          "content_hash",
          "pinned_at"
        ],
        "additionalProperties": false
      },
      "Item": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "kind": {
            "type": "string",
            "enum": [
              "fragment",
              "thread"
            ],
            "description": "Authored kind, fixed at the first publish (§5.3)."
          },
          "draft_md": {
            "type": "string",
            "description": "Studio-private draft, [TK] grammar included."
          },
          "draft_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "type": "integer",
            "description": "Latest published version; 0 for a draft."
          },
          "withdrawn": {
            "type": "boolean"
          },
          "page": {
            "type": [
              "string",
              "null"
            ],
            "description": "Origin-relative permalink (§5.8), fixed at first publish."
          },
          "forked_from": {
            "$ref": "#/components/schemas/Reference"
          },
          "stub_of": {
            "$ref": "#/components/schemas/StubOf"
          },
          "generation": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GenMeta"
            }
          },
          "first_published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "draft_updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "draft_rev": {
            "type": "string",
            "description": "Names the draft's state: draft_md, draft_note and generation. Send it back as draft_rev on PATCH or publish to change only the draft you saw. It is a hash, so equal drafts have equal revisions."
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "withdrawn"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "versions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Version"
            },
            "description": "Every published version, on GET /api/items/{id}."
          },
          "content_html": {
            "type": "string",
            "description": "The current version's content_html, on GET /api/items only. Absent for a draft never published and for a withdrawn item. It bakes other origins' bytes (§10.2): sanitize before rendering (§14)."
          },
          "unpublished_changes": {
            "type": "boolean",
            "description": "On GET /api/items only: present and true when a published item's draft differs from its current version, so publishing would change it."
          }
        },
        "required": [
          "id",
          "kind",
          "draft_md",
          "draft_note",
          "version",
          "withdrawn",
          "page",
          "first_published_at",
          "published_at",
          "created_at",
          "draft_updated_at",
          "state",
          "draft_rev"
        ],
        "additionalProperties": false
      },
      "ItemCreate": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "fragment",
              "thread"
            ],
            "description": "Fixed at the first publish (§5.3): a fragment never becomes a thread, nor a thread a fragment. Default fragment; thread with stub_of; the source's kind for a fork without content. A client creating items on an author's behalf should send thread, since only the author can say that an item is a leaf (§5.3, decision #100)."
          },
          "content_md": {
            "type": "string"
          },
          "forked_from": {
            "$ref": "#/components/schemas/Reference",
            "description": "§5.6 lineage, immutable. Without content_md, the draft starts as the pinned source flattened (§5.6 rule 6)."
          },
          "stub_of": {
            "$ref": "#/components/schemas/StubTarget",
            "description": "Makes the draft a stub (§10.6). Without content_md, a blyg stub starts as ![[id]]."
          }
        },
        "additionalProperties": false
      },
      "ItemPatch": {
        "type": "object",
        "properties": {
          "content_md": {
            "type": "string"
          },
          "note": {
            "type": "string",
            "description": "Note for the next publish; empty clears."
          },
          "generation": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/GenMeta"
            },
            "description": "Per [TK] scope, by position; null clears."
          },
          "draft_rev": {
            "type": "string",
            "description": "Apply the edit only if the draft is still at this revision; otherwise 409 stale and nothing changes. Absent, the edit applies to whatever the draft holds."
          }
        },
        "additionalProperties": false
      },
      "PublishRequest": {
        "type": "object",
        "properties": {
          "note": {
            "type": "string"
          },
          "note_generated": {
            "type": "boolean",
            "description": "The client wrote the note, not the author (§5.2)."
          },
          "draft_rev": {
            "type": "string",
            "description": "Publish only if the draft is still at this revision; otherwise 409 stale and nothing is published."
          }
        },
        "additionalProperties": false
      },
      "NoteRequest": {
        "type": "object",
        "properties": {
          "note": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "PublishResult": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/Item"
          },
          "version": {
            "$ref": "#/components/schemas/Version"
          },
          "warnings": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "item",
          "version"
        ],
        "additionalProperties": false
      },
      "WithdrawResult": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/Item"
          },
          "version": {
            "$ref": "#/components/schemas/Version"
          }
        },
        "required": [
          "item",
          "version"
        ],
        "additionalProperties": false
      },
      "PinResult": {
        "type": "object",
        "properties": {
          "version": {
            "$ref": "#/components/schemas/Version"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "version",
          "url"
        ],
        "additionalProperties": false
      },
      "ItemList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          }
        },
        "required": [
          "items"
        ],
        "additionalProperties": false
      },
      "Hopper": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "public": {
            "type": "boolean"
          },
          "slug_frozen": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "member_count": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "public",
          "slug_frozen",
          "created_at",
          "updated_at",
          "member_count"
        ],
        "additionalProperties": false
      },
      "HopperName": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "OwnRef": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "withdrawn"
            ]
          },
          "version": {
            "type": "integer"
          },
          "page": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "item_id",
          "state",
          "version",
          "page"
        ],
        "additionalProperties": false
      },
      "ImportRef": {
        "type": "object",
        "properties": {
          "subscription_id": {
            "type": "integer"
          },
          "origin": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "current",
              "withdrawn"
            ]
          },
          "version": {
            "type": "integer"
          },
          "page": {
            "type": [
              "string",
              "null"
            ]
          },
          "doc": {
            "$ref": "#/components/schemas/ImportedDoc"
          }
        },
        "required": [
          "subscription_id",
          "origin",
          "item_id",
          "kind",
          "state",
          "version",
          "page",
          "doc"
        ],
        "additionalProperties": false
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "added_at": {
            "type": "string",
            "format": "date-time"
          },
          "own": {
            "$ref": "#/components/schemas/OwnRef"
          },
          "imported": {
            "$ref": "#/components/schemas/ImportRef"
          }
        },
        "required": [
          "id",
          "added_at"
        ],
        "additionalProperties": false
      },
      "HopperDetail": {
        "type": "object",
        "properties": {
          "hopper": {
            "$ref": "#/components/schemas/Hopper"
          },
          "members": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Member"
            }
          }
        },
        "required": [
          "hopper",
          "members"
        ],
        "additionalProperties": false
      },
      "HopperList": {
        "type": "object",
        "properties": {
          "hoppers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hopper"
            }
          }
        },
        "required": [
          "hoppers"
        ],
        "additionalProperties": false
      },
      "MemberCreate": {
        "description": "Exactly one of own_item_id or imported. An import is named by subscription_id, or by origin.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "own_item_id": {
                "type": "string",
                "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
                "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
              }
            },
            "required": [
              "own_item_id"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "imported": {
                "type": "object",
                "properties": {
                  "subscription_id": {
                    "type": "integer"
                  },
                  "origin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "imported"
            ],
            "additionalProperties": false
          }
        ]
      },
      "Created": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "Mention": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "target_item_id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "source_url": {
            "type": "string"
          },
          "target_url": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "failed",
              "gone"
            ]
          },
          "relation": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "stub",
              "transclusion",
              "fork",
              "source",
              "link",
              null
            ]
          },
          "class": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "response",
              "notice",
              null
            ],
            "description": "Set with relation (§15.5). A notice is a link, or a stub or transclusion from a document with no words of its own (a repost); it is never shown among responses and cannot be approved."
          },
          "source_origin": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_item_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "source_kind": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_author": {
            "description": "Arbitrary JSON, passed through verbatim."
          },
          "source_page": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure": {
            "type": [
              "string",
              "null"
            ]
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "verified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "source_host": {
            "type": "string"
          },
          "approved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Shown on the target's page since then (§15.5). Cleared when a re-verification finds the relation, class, origin, page or author changed, or the mention stops verifying."
          },
          "blocked": {
            "type": "boolean",
            "description": "The source is blocked. Such mentions are listed only with include_blocked=true."
          }
        },
        "required": [
          "id",
          "target_item_id",
          "source_url",
          "target_url",
          "status",
          "relation",
          "class",
          "received_at",
          "verified_at",
          "source_host",
          "approved_at",
          "blocked"
        ],
        "additionalProperties": false
      },
      "MentionList": {
        "type": "object",
        "properties": {
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            }
          }
        },
        "required": [
          "mentions"
        ],
        "additionalProperties": false
      },
      "Outbound": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "source_item_id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          },
          "relation": {
            "type": "string",
            "enum": [
              "stub",
              "transclusion",
              "fork",
              "source",
              "link",
              "url"
            ]
          },
          "target_url": {
            "type": "string"
          },
          "target_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "sent",
              "failed",
              "no_endpoint",
              "abandoned"
            ]
          },
          "endpoint": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "last_result": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "source_item_id",
          "relation",
          "target_url",
          "target_version",
          "status",
          "endpoint",
          "attempts",
          "last_result",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "OutboundList": {
        "type": "object",
        "properties": {
          "outbound": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Outbound"
            }
          }
        },
        "required": [
          "outbound"
        ],
        "additionalProperties": false
      },
      "Token": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the token stops authenticating; null never."
          }
        },
        "required": [
          "id",
          "name",
          "scopes",
          "created_at",
          "last_used_at",
          "revoked_at",
          "expires_at"
        ],
        "additionalProperties": false
      },
      "TokenList": {
        "type": "object",
        "properties": {
          "tokens": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Token"
            }
          }
        },
        "required": [
          "tokens"
        ],
        "additionalProperties": false
      },
      "TokenMint": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            },
            "description": "Only scopes the calling token holds."
          },
          "expires_in": {
            "type": "integer",
            "minimum": 1,
            "description": "Seconds until the token expires. Absent, it expires with the minting token, or never if that never does. Never later than the minting token: a minted token cannot outlive its minter, as it cannot hold a scope its minter lacks."
          }
        },
        "required": [
          "name",
          "scopes"
        ],
        "additionalProperties": false
      },
      "TokenMinted": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "token": {
            "type": "string",
            "description": "Shown once."
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "note": {
            "type": "string"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it stops authenticating; null never."
          }
        },
        "required": [
          "id",
          "token",
          "scopes",
          "note",
          "expires_at"
        ],
        "additionalProperties": false
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The remote origin id; scopes imported item ids (§13.1)."
          },
          "kind": {
            "type": "string",
            "enum": [
              "blyg",
              "l0"
            ]
          },
          "origin": {
            "type": "string",
            "description": "Identity origin (§12.2), or the final feed URL for L0."
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "author": {
            "type": [
              "object",
              "null"
            ],
            "description": "The manifest's publication identity (§6.1), as the origin asserts it: an opaque object, name RECOMMENDED (§5.5). Relative URLs in it resolve against origin. Readers fall back to it when an item has no author. Null when the manifest has none, or for L0."
          },
          "display_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "site_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "in_blogroll": {
            "type": "boolean"
          },
          "site_discrepancy": {
            "type": [
              "string",
              "null"
            ]
          },
          "lossy": {
            "type": "boolean"
          },
          "items": {
            "type": "integer"
          },
          "unread": {
            "type": "integer"
          },
          "discrepancies": {
            "type": "integer"
          },
          "last_polled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "next_poll_at": {
            "type": "string",
            "format": "date-time"
          },
          "poll_failures": {
            "type": "integer"
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "kind",
          "origin",
          "title",
          "display_title",
          "in_blogroll",
          "site_discrepancy",
          "lossy",
          "items",
          "unread",
          "discrepancies",
          "last_polled_at",
          "next_poll_at",
          "poll_failures",
          "last_error",
          "created_at",
          "author"
        ],
        "additionalProperties": false
      },
      "SubscriptionList": {
        "type": "object",
        "properties": {
          "subscriptions": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Subscription"
            }
          }
        },
        "required": [
          "subscriptions"
        ],
        "additionalProperties": false
      },
      "SubscriptionPatch": {
        "type": "object",
        "properties": {
          "display_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "in_blogroll": {
            "type": "boolean",
            "description": "Publishes or withdraws a blogroll entry (§11). Needs origin:write as well."
          }
        },
        "additionalProperties": false
      },
      "Resolution": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "blyg",
              "l0"
            ]
          },
          "identity": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "site_url": {
            "type": "string"
          },
          "site_discrepancy": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "trail": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "kind",
          "identity",
          "trail"
        ],
        "additionalProperties": false
      },
      "SubscribeResult": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/Subscription"
          },
          "resolution": {
            "$ref": "#/components/schemas/Resolution"
          }
        },
        "required": [
          "subscription",
          "resolution"
        ],
        "additionalProperties": false
      },
      "ReresolveResult": {
        "type": "object",
        "properties": {
          "current": {
            "type": "string"
          },
          "resolution": {
            "$ref": "#/components/schemas/Resolution"
          },
          "changed": {
            "type": "boolean"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "current",
          "resolution",
          "changed",
          "note"
        ],
        "additionalProperties": false
      },
      "MoveResult": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/Subscription"
          },
          "resolution": {
            "$ref": "#/components/schemas/Resolution"
          },
          "notes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "subscription",
          "resolution"
        ],
        "additionalProperties": false
      },
      "Pin": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          },
          "doc": {
            "$ref": "#/components/schemas/PinDocument"
          }
        },
        "required": [
          "version",
          "url",
          "doc"
        ],
        "additionalProperties": false
      },
      "ReaderItem": {
        "type": "object",
        "properties": {
          "subscription_id": {
            "type": "integer"
          },
          "origin": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fragment",
              "thread",
              "withdrawn",
              "l0"
            ]
          },
          "l0": {
            "type": "boolean"
          },
          "state": {
            "type": "string",
            "enum": [
              "current",
              "withdrawn"
            ]
          },
          "version": {
            "type": "integer"
          },
          "page": {
            "type": [
              "string",
              "null"
            ]
          },
          "claimed_updated": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "first_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "sort_at": {
            "type": "string",
            "format": "date-time"
          },
          "read": {
            "type": "boolean"
          },
          "discrepancy": {
            "type": [
              "string",
              "null"
            ]
          },
          "doc": {
            "$ref": "#/components/schemas/ImportedDoc"
          },
          "pins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pin"
            }
          }
        },
        "required": [
          "subscription_id",
          "origin",
          "source",
          "item_id",
          "kind",
          "l0",
          "state",
          "version",
          "page",
          "claimed_updated",
          "first_seen_at",
          "sort_at",
          "read",
          "discrepancy",
          "doc"
        ],
        "additionalProperties": false
      },
      "FeedPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/ReaderItem"
            }
          },
          "next": {
            "type": "string",
            "description": "Cursor for the next page; empty at the end."
          },
          "notice": {
            "type": "string"
          },
          "as_of": {
            "type": "string",
            "format": "date-time",
            "description": "When this page was read. Send the first page's to POST /api/reader/read to mark read what you showed and nothing that arrived since."
          }
        },
        "required": [
          "items",
          "next",
          "notice",
          "as_of"
        ],
        "additionalProperties": false
      },
      "ReaderItemResult": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/ReaderItem"
          },
          "notice": {
            "type": "string"
          }
        },
        "required": [
          "item",
          "notice"
        ],
        "additionalProperties": false
      },
      "Media": {
        "type": "object",
        "additionalProperties": false,
        "description": "An uploaded object (§5.4). Its path is derived from its bytes, so it never changes meaning.",
        "properties": {
          "path": {
            "type": "string",
            "description": "Origin-relative; write it in markdown as ![alt](media/…)."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "mime": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/gif",
              "image/webp"
            ]
          },
          "size": {
            "type": "integer"
          },
          "sha256": {
            "type": "string"
          },
          "published": {
            "type": "boolean",
            "description": "Referenced by a published version: served publicly and kept forever (§8 rules 2 and 4). Until then it 404s and may be deleted."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "path",
          "url",
          "mime",
          "size",
          "sha256",
          "published",
          "created_at"
        ]
      },
      "MediaList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Media"
            }
          }
        },
        "required": [
          "media"
        ]
      },
      "HopperPatch": {
        "type": "object",
        "additionalProperties": false,
        "description": "At least one of name or public.",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The slug follows the name until the hopper has ever been public."
          },
          "public": {
            "type": "boolean",
            "description": "Show the list at {origin}h/{slug}/ (§13.5): excerpts with attribution and links, served live, never part of the protocol surface. Going public freezes the slug for good. Needs origin:write as well."
          }
        }
      },
      "Block": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "host",
              "domain"
            ]
          },
          "value": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "kind",
          "value",
          "created_at"
        ]
      },
      "BlockList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Block"
            }
          }
        },
        "required": [
          "blocks"
        ]
      },
      "BlockCreate": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "host",
              "domain"
            ],
            "description": "domain blocks the registrable domain and every subdomain of it."
          },
          "value": {
            "type": "string",
            "description": "A host, a domain, or a URL to take one from."
          }
        },
        "required": [
          "kind",
          "value"
        ]
      },
      "Link": {
        "type": "object",
        "properties": {
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "The target's identity origin; omitted for an own item (§10.3a)."
          },
          "id": {
            "type": "string",
            "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
            "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
          }
        },
        "required": [
          "id"
        ],
        "description": "A links[] entry (§10.3a): the item a resolved [[id]] link names. Not a reference: no version, no cited.",
        "additionalProperties": false
      },
      "ItemDocument": {
        "type": "object",
        "description": "The origin's items/{id}.json (§5), verbatim (jsonb orders its keys). blygd checked only that id names the item, kind is one it knows, and version is at least 1: every other member is the origin's unverified assertion, and members this description does not list may appear. Sanitize content_html (§14).",
        "properties": {
          "blyg": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fragment",
              "thread"
            ]
          },
          "origin": {
            "type": "string"
          },
          "page": {
            "type": "string",
            "description": "Origin-relative or absolute (§5.8)."
          },
          "author": {
            "description": "Opaque byline object (§5.5)."
          },
          "created": {
            "type": "string"
          },
          "updated": {
            "type": "string"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "content_md": {
            "type": "string"
          },
          "content_html": {
            "type": "string",
            "description": "The origin's HTML. Sanitize (§14)."
          },
          "content_hash": {
            "type": "string",
            "description": "Checked against content_md; a mismatch is the item's discrepancy (§13.3)."
          },
          "media": {
            "type": "array"
          },
          "transclusions": {
            "type": "array"
          },
          "stub_of": {
            "type": "object"
          },
          "forked_from": {
            "type": "object"
          },
          "generated": {
            "type": "array"
          },
          "links": {
            "type": "array"
          },
          "changelog": {
            "type": "array"
          }
        },
        "required": [
          "id",
          "kind",
          "version"
        ]
      },
      "L0Document": {
        "type": "object",
        "description": "A wrapped legacy RSS entry (§13.6). blygd's own shape, not a protocol document: it never leaves this instance except through this API. Mark it visibly as legacy content.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "l0"
            ]
          },
          "guid": {
            "type": "string"
          },
          "link": {
            "type": "string",
            "description": "The entry's URL. A response to it is a {url} stub (§10.6)."
          },
          "title": {
            "type": "string"
          },
          "summary_html": {
            "type": "string",
            "description": "The entry's summary or description, verbatim and capped at 64 KB. Sanitize (§14)."
          },
          "summary_text": {
            "type": "string",
            "description": "Plain text, cut to 1,000 characters (§5.3's fragment ethos)."
          },
          "published": {
            "type": "string",
            "description": "As the feed claims it."
          },
          "feed": {
            "type": "string",
            "description": "The feed it came from."
          },
          "note": {
            "type": "string",
            "description": "Says what the wrapper is."
          }
        },
        "required": [
          "kind",
          "summary_html",
          "summary_text",
          "feed",
          "note"
        ],
        "additionalProperties": false
      },
      "ImportedDoc": {
        "description": "The imported item's content: the origin's document for a blyg, blygd's wrapper for L0, or null once withdrawn (§13.4).",
        "oneOf": [
          {
            "type": "null"
          },
          {
            "$ref": "#/components/schemas/ItemDocument"
          },
          {
            "$ref": "#/components/schemas/L0Document"
          }
        ]
      },
      "PinDocument": {
        "type": "object",
        "description": "The origin's items/{id}/v{n}.json (§8), verbatim. blygd checked only that id and version name this pin and kind is not withdrawn; every other member is the origin's assertion. Sanitize content_html (§14).",
        "properties": {
          "blyg": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "at": {
            "type": "string"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "pinned": {
            "type": "boolean"
          },
          "origin": {
            "type": "string"
          },
          "author": {
            "description": "Opaque byline object (§5.5)."
          },
          "content_md": {
            "type": "string"
          },
          "content_html": {
            "type": "string",
            "description": "The origin's HTML. Sanitize (§14)."
          },
          "content_hash": {
            "type": "string"
          },
          "transclusions": {
            "type": "array"
          },
          "stub_of": {
            "type": "object"
          },
          "forked_from": {
            "type": "object"
          },
          "generated": {
            "type": "array"
          }
        },
        "required": [
          "id",
          "version"
        ]
      },
      "MarkAllRead": {
        "type": "object",
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date-time",
            "description": "The as_of of the feed you showed."
          },
          "subscription_id": {
            "type": "integer",
            "minimum": 1,
            "description": "Only this subscription's items; absent, every subscription's."
          }
        },
        "required": [
          "as_of"
        ],
        "additionalProperties": false
      },
      "MarkAllReadResult": {
        "type": "object",
        "properties": {
          "marked": {
            "type": "integer",
            "description": "Items that were unread and are now read."
          }
        },
        "required": [
          "marked"
        ],
        "additionalProperties": false
      },
      "ImportRequest": {
        "type": "object",
        "description": "Exactly one of opml or url.",
        "properties": {
          "opml": {
            "type": "string",
            "description": "An OPML document, up to the 1 MB request limit."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "An OPML file, or a blyg whose manifest names a blogroll."
          }
        },
        "additionalProperties": false
      },
      "ImportResult": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "integer",
            "description": "Entries with an http(s) URL, at most 1000."
          },
          "queued": {
            "type": "integer",
            "description": "New entries, and failed ones queued again."
          }
        },
        "required": [
          "entries",
          "queued"
        ],
        "additionalProperties": false
      },
      "ImportEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "url": {
            "type": "string",
            "description": "The entry's xmlUrl, or its htmlUrl."
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "The entry's text, as the list wrote it."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "subscribed",
              "failed"
            ]
          },
          "subscription_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Once subscribed."
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "The last failure. A pending entry with one is waiting to try again; three failures and it fails."
          },
          "attempts": {
            "type": "integer"
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "url",
          "title",
          "status",
          "subscription_id",
          "error",
          "attempts",
          "next_attempt_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "ImportList": {
        "type": "object",
        "properties": {
          "imports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImportEntry"
            }
          }
        },
        "required": [
          "imports"
        ],
        "additionalProperties": false
      },
      "ClearResult": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "integer"
          }
        },
        "required": [
          "deleted"
        ],
        "additionalProperties": false
      },
      "PreviewRequest": {
        "type": "object",
        "properties": {
          "content_md": {
            "type": "string",
            "description": "Preview this in place of the saved draft; absent, the saved draft."
          }
        },
        "additionalProperties": false
      },
      "Preview": {
        "type": "object",
        "properties": {
          "content_md": {
            "type": "string",
            "description": "The wire content_md: [TK] scopes stripped to their output (§5.7). Empty when a scope has no output yet."
          },
          "content_html": {
            "type": "string",
            "description": "As publish would bake it, other origins' bytes included (§10.2). A directive that cannot bake is a blockquote of class \"blyg-transclusion unresolved\" saying why. Sanitize before rendering (§14)."
          },
          "transclusions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reference"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            }
          },
          "generated": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Generated"
            }
          },
          "problems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Problem"
            },
            "description": "Every reason a publish would be refused now; empty means it would go through. A refusal of the draft as a whole is at \"draft\"."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What a publish would warn about, such as a quote of an unpinned remote version."
          },
          "notice": {
            "type": "string"
          }
        },
        "required": [
          "content_md",
          "content_html",
          "transclusions",
          "links",
          "generated",
          "problems",
          "warnings",
          "notice"
        ],
        "additionalProperties": false
      },
      "InviteRedeem": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The invite code, `blygd-invite-…`."
          },
          "handle": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$",
            "description": "1–63 lowercase letters, digits or hyphens, not starting with a hyphen; a few are reserved. It is in the blyg's URL for good."
          },
          "title": {
            "type": "string",
            "maxLength": 200,
            "description": "The blyg's title; editable later (PATCH /api/origin)."
          }
        },
        "required": [
          "code",
          "handle"
        ],
        "additionalProperties": false
      },
      "InviteRedeemed": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "format": "uri",
            "description": "The new blyg's base URL."
          },
          "token": {
            "type": "string",
            "description": "The owner token (`*`, never expiring). Shown once."
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "handle",
          "origin",
          "token",
          "note"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, unknown or revoked token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The token lacks the scope this operation needs.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found, or not yours.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflicts with current state, or an invariant refused the change.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Invalid": {
        "description": "Well-formed but not acceptable; see message and, for publish, problems.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "Over the upload cap (BLYGD_MEDIA_MAX_BYTES).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Over a request budget. Wait for Retry-After seconds. Budgets are per token and per user, by the operation's x-blygd-cost class; an address with too many failed authentications is refused too.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until a request of this class is allowed.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "parameters": {
      "ItemID": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-hjkmnp-tv-z]{26}$",
          "description": "Item id (§5.1): 26 characters of lowercase Crockford base32."
        }
      },
      "VersionN": {
        "name": "n",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "HopperID": {
        "name": "hid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "MemberID": {
        "name": "mid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "TokenID": {
        "name": "tid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "SubscriptionID": {
        "name": "sid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "ImportedItemID": {
        "name": "iid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Item id as scoped by the subscription; an L0 id is l0: plus hex."
      },
      "MediaFile": {
        "name": "file",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-f]{32}\\.(png|jpg|gif|webp)$"
        },
        "description": "The file name under media/."
      },
      "MentionID": {
        "name": "mid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "BlockID": {
        "name": "bid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  }
}
