{
  "openapi": "3.1.0",
  "info": {
    "title": "Theirway API",
    "description": "File delivery for photographers and studios. Authenticate with a personal access token (`Authorization: Bearer tw_pat_...`), made in the Theirway app under Access tokens. File bytes never pass through this API: uploads go straight to storage through presigned part URLs.",
    "license": {
      "name": ""
    },
    "version": "1"
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "paths": {
    "/deliveries": {
      "get": {
        "tags": [
          "deliveries"
        ],
        "summary": "The producer's deliveries, newest first. By default the active ones;\n`?state=deleted` lists the recently deleted ones instead, each with the\ndays left to restore it.",
        "operationId": "list_deliveries",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "description": "`next_cursor` from the previous page; leave out for the first page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1 to 100. Default 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Which deliveries: `active` (the default) or `deleted`, the recently\ndeleted ones, including those being erased. An erased delivery is\nlisted in neither.",
            "required": false,
            "schema": {
              "type": "string",
              "description": "What a list asks for. The list of deleted deliveries includes the ones\nbeing erased, which the producer can no longer restore but should see are\non their way out.",
              "enum": [
                "active",
                "deleted"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryPage"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "deliveries"
        ],
        "summary": "Start a delivery. Send an `Idempotency-Key` so a retry returns the same\ndelivery instead of creating a second one.",
        "operationId": "create_delivery",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Any unique string, e.g. a UUID; a retry with the same key and body returns the original response.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDelivery"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Delivery"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}": {
      "get": {
        "tags": [
          "deliveries"
        ],
        "summary": "One delivery: its files, recipients and events.",
        "operationId": "get_delivery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryDetail"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "delete": {
        "tags": [
          "deliveries"
        ],
        "summary": "Delete a delivery. It stops working at once for everyone it was sent to\n(they see that it was deleted and who by), and you can restore it for 30\ndays; after that its files, events and the names and addresses of the\npeople it was sent to are erased. Its files stop counting toward your\nstorage now. Answers at once, whatever the size of the delivery.",
        "operationId": "delete_delivery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedResponse"
                }
              }
            }
          },
          "409": {
            "description": "The delivery is being erased."
          },
          "410": {
            "description": "The delivery was erased."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/SHA256SUMS": {
      "get": {
        "tags": [
          "deliveries"
        ],
        "summary": "The list of files this frozen delivery was fixed with, as `sha256sum -c`\nreads it. Check a download of the whole delivery against it; `sha256sum\nSHA256SUMS` gives the checksum of the list that the page shows. 404 unless\nthe delivery is frozen.",
        "operationId": "get_owner_sums",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not yours, or not frozen, or its list was erased."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/description": {
      "put": {
        "tags": [
          "deliveries"
        ],
        "summary": "Set the delivery's release notes: the text at the top of the client's\npage. The whole text is sent, so repeating a request changes nothing;\nempty clears it. Only a delivery that is not deleted can be changed.",
        "operationId": "set_description",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DescriptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryDescription"
                }
              }
            }
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased."
          },
          "422": {
            "description": "Longer than 10,000 characters, or not plain text."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/erase": {
      "post": {
        "tags": [
          "deliveries"
        ],
        "summary": "Erase a delivery now instead of waiting out the 30 days: its files, events\nand the names and addresses of the people it was sent to are erased in the\nbackground, and this cannot be undone or cancelled. Answers 202 at once,\nwhatever the size of the delivery; its files stop counting toward your\nstorage now, and the space comes back to the bucket within a week after\nthe erasing is done. Its snapshots are NOT erased: the answer names them\n(`snapshots_kept`), and each is erased by its own call.",
        "operationId": "erase_now",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Already erased.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErasingResponse"
                }
              }
            }
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErasingResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/events": {
      "get": {
        "tags": [
          "deliveries"
        ],
        "summary": "A delivery's events, newest first: the way to follow whether the\nclient has opened and downloaded it.",
        "operationId": "list_events",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "`next_cursor` from the previous page; leave out for the first page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1 to 100. Default 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files": {
      "get": {
        "tags": [
          "files"
        ],
        "summary": "A delivery's files, ordered by path, a page at a time.",
        "operationId": "list_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "`next` from the previous page; leave out for the first page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Files per page, 1 to 200. Default 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilePage"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Put a file you already have stored into this delivery, without uploading\nit again. Attaching the same stored file at the same path twice returns\nthe first attachment. A file that was part of a delivery Theirway removed\nanswers 409 of type `file-removed-by-theirway`.",
        "operationId": "attach_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryFile"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/download-links": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Links to download many files of your delivery at once, up to 200 a call:\nevery file but one Theirway took down, held and retracted ones too. A\nfile Theirway took down is named in `unavailable`; an id that is not a\nfile of this delivery is in neither list. Each link is an attachment,\nsigned to ask for type `application/octet-stream`, and works for 15\nminutes. Nothing is recorded on the delivery: your own download is not\nyour client's.",
        "operationId": "download_links",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DownloadLinksRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerDownloadLinks"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 200."
          },
          "404": {
            "description": "Not your delivery."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/lookup": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Which of these files is already stored for you, by content. Only your\nown stored files can match.",
        "operationId": "lookup_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LookupRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/meta": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Add tags, take tags off, or set the note on many files of one delivery,\nall or none: if any file is not this delivery's (404), or would end up\nwith more than 20 tags (400), nothing changes.",
        "operationId": "edit_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditFilesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilesUpdated"
                }
              }
            }
          },
          "400": {
            "description": "A tag or the note breaks a limit, or a file would end up with more than 20 tags; nothing was changed."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/prune": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Prune files: each leaves the delivery for good, and Theirway keeps a\nrecord of it: its name, size and SHA-256 if it has one (`null` when it had\nnone). A client's page shown as Files draws that record as a line; a page\nshown as Pictures only says that some files were removed. NOT reversible.\nA file another of your active deliveries holds stays stored there. A file\nalready pruned is `unchanged`, so repeating a call is harmless. All or\nnone: an id that is not this delivery's is a 404 and nothing is pruned.",
        "operationId": "prune_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PruneRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pruned"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 200."
          },
          "404": {
            "description": "A file that is not this delivery's."
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/prune-preview": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "What pruning these files would do, without doing it: how much storage it\nfrees now, which files other deliveries of yours keep, and your account's\nusage. Changes nothing.",
        "operationId": "prune_preview",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PruneRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preview"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 200."
          },
          "404": {
            "description": "A file that is not this delivery's."
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/reinstate": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Put retracted files back: they download again. The reference forgets the\nreason; the trail keeps both moves. A file Theirway took down cannot be\nreinstated (409, `file-removed-by-theirway`).",
        "operationId": "reinstate_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReinstateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reinstated"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 500."
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased; or a file was taken down by Theirway."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/release": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Release files someone sent you through a request: the people you sent this\ndelivery to see them from now on. Nothing checked what is in a file that\nwaited here, so download and look first (`GET .../files/{id}/download`).\nThe delivery must not be frozen. All or none: an id that is not this\ndelivery's is a 404 and nothing is released.",
        "operationId": "release_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReleaseRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Released"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 500."
          },
          "409": {
            "description": "The delivery is deleted, being erased, erased or frozen; or a file was taken down by Theirway."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/retract": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Retract files: the client's page shows each struck, with the reason, and\nnothing signs a link to it. Reversible (`reinstate`). It reaches only this\ndelivery's references unless `everywhere` is true: another delivery holding\nthe same bytes still serves them, and `still_in` says which. All or none:\nan id that is not this delivery's is a 404 and nothing is retracted.",
        "operationId": "retract_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetractRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Retracted"
                }
              }
            }
          },
          "400": {
            "description": "No files, more than 500, or a reason that is not 1 to 500 characters of plain text."
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}": {
      "delete": {
        "tags": [
          "files"
        ],
        "summary": "Take a file out of this delivery. The stored file, and every other\ndelivery that uses it, is untouched; if this was the last use, the bytes\nare deleted a week later unless they are attached somewhere again.",
        "operationId": "remove_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The file is out of the delivery."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "patch": {
        "tags": [
          "files"
        ],
        "summary": "Change one file's tags and note: what you send replaces, what you leave\nout stays. Answers with the file as the lists show it.",
        "operationId": "edit_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditFileRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryFile"
                }
              }
            }
          },
          "400": {
            "description": "A tag or the note breaks a limit; the detail says which and what to do."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}/download": {
      "get": {
        "tags": [
          "files"
        ],
        "summary": "A link to download one file of your delivery, in any state but one\nTheirway took down. Always an attachment, signed to ask for type\n`application/octet-stream`.",
        "operationId": "download_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerDownload"
                }
              }
            }
          },
          "404": {
            "description": "Not a file of this delivery."
          },
          "409": {
            "description": "Theirway took the file down."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}/preview": {
      "get": {
        "tags": [
          "files"
        ],
        "summary": "The preview of one file of your delivery: the picture, or a video's\nplayable copy and poster, that your client's viewer shows, never the\noriginal. Any file but one Theirway took down, held and retracted ones\ntoo. A 200 is one of three shapes: a picture (`url`, no `kind`), a video\n(`kind`: `video`) or a video's poster (`kind`: `image`, with `video`).\nEach link is inline and works for 15 minutes. Nothing is recorded on the\ndelivery.",
        "operationId": "preview_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewAnswer"
                }
              }
            }
          },
          "202": {
            "description": "Being made: ask again in a few seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewPreparing"
                }
              }
            }
          },
          "404": {
            "description": "Not a file of this delivery, or one that will never have a preview."
          },
          "409": {
            "description": "Theirway took the file down."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}/thumbnail": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "A link to upload this file's thumbnail (WebP, up to 256 KiB) to, or\n`null` when it already has one.",
        "operationId": "start_thumbnail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThumbnailUpload"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}/thumbnail/complete": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Check what was PUT and, if it fits, keep it as the file's thumbnail. An\nobject over 256 KiB is deleted and refused with 422.",
        "operationId": "complete_thumbnail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The thumbnail is kept."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/files/{file_id}/unpack": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Unpack a zip file of this delivery: the files inside are added in a folder\nnamed after the zip, and the zip stays. It runs in the background; the zip's\nentry in `GET /deliveries/{id}` carries `unpack` while it runs and after.",
        "operationId": "unpack_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unpacking"
                }
              }
            }
          },
          "409": {
            "description": "The file is waiting for your release, retracted or taken down; the zip is already being unpacked; or the delivery is not editable."
          },
          "422": {
            "description": "The file is not named like a zip."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/mode": {
      "put": {
        "tags": [
          "deliveries"
        ],
        "summary": "Keep this delivery up to date (`\"maintained\"`: its page lists the newest\nfiles first), or settle it (`\"one_off\"`). The mode says what the delivery\nIS, so asking for the one it has answers `\"changed\": false`. Only a\ndelivery that is not deleted can be changed, and a frozen one (a snapshot)\nnever: it answers 409.",
        "operationId": "set_mode",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Applied"
                }
              }
            }
          },
          "409": {
            "description": "The delivery is deleted, being erased or erased, or it is frozen (a frozen delivery stays so)."
          },
          "422": {
            "description": "Not one of the two modes."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/options": {
      "patch": {
        "tags": [
          "deliveries"
        ],
        "summary": "Turn rails on or off for one delivery. Off by default; this is the only\nway to turn one on. Turning one off stops new tests and transfers, and\nleaves a transfer that is already running to finish.",
        "operationId": "set_options",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OptionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryOptions"
                }
              }
            }
          },
          "422": {
            "description": "An unknown or repeated rail."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/recipients": {
      "post": {
        "tags": [
          "recipients"
        ],
        "summary": "Create a link that lets one recipient download the delivery. To email it\nfrom Theirway, call `POST .../recipients/{recipient_id}/email`. `email`, if\ngiven, must be an email address; a link made without one can be given one\nlater, once, with `POST .../recipients/{recipient_id}/address`.",
        "operationId": "create_recipient",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Any unique string, e.g. a UUID; a retry with the same key and body returns the original link.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRecipientRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateRecipientResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "recipients:send"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/recipients/{recipient_id}/address": {
      "post": {
        "tags": [
          "recipients"
        ],
        "summary": "Give a link that has no email address one. It is set once: a link with an\naddress keeps it (answer 409), so for another address make a new link. The\nsame address again is answered 200. Adding never sends: to email the link,\ncall `POST .../recipients/{recipient_id}/email`.",
        "operationId": "add_address",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RecipientId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddAddressRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddAddressResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "recipients:send"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/recipients/{recipient_id}/avatar": {
      "get": {
        "tags": [
          "recipients"
        ],
        "summary": "The picture of a person this delivery was sent to, from Gravatar, if\ntheir address has one. A recipient without an address has no picture.",
        "operationId": "recipient_avatar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RecipientId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The picture: image/jpeg, image/png, image/webp or image/gif.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0
                  }
                }
              }
            }
          },
          "404": {
            "description": "No picture: none exists, the recipient has no address or is not on this delivery, or avatars are switched off."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/recipients/{recipient_id}/email": {
      "get": {
        "tags": [
          "recipients"
        ],
        "summary": "What the email would say and whether it may be sent now. The text holds\nthe link, which is why this needs the same scope as the send. `notice`\nsays why not, or when the link was last emailed; the times are RFC 3339 UTC\nfields so an app can write them in the person's own time zone.",
        "operationId": "preview_link_email",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RecipientId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPreview"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "recipients:send"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "recipients"
        ],
        "summary": "Email the link to the address on it. The email is fixed words, sent from\n`Theirway <delivery@theirway.app>` with Reply-To your own address, and it\ncarries the link. Answers `sent` once Lettermint has taken it, which is not\n\"delivered\". No body: the address is the one stored on the link.",
        "operationId": "email_link",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RecipientId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendAnswer"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "recipients:send"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/request": {
      "get": {
        "tags": [
          "requests"
        ],
        "summary": "The delivery's file request: its state, caps, room, who has sent what, and\n(with the `requests:write` scope) the link to send. 404 when the delivery\nhas none.",
        "operationId": "get_request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "requests"
        ],
        "summary": "Ask others for files: makes the delivery's file request, open for 14 days\nunless `closes_at` says otherwise, and answers with it, link included. A\ndelivery has at most one (409). The caps are held to the account's quota.\nA delivery somebody already has a link to is refused (409) until\n`?recipients_see_contributions=true` when a contribution would reach them\nbefore the owner's release: a served file is a delivery file the moment it\nlands, and every recipient link lists it. A request that holds everything\n(`accepts: any`) needs no confirmation.",
        "operationId": "create_request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipients_see_contributions",
            "in": "query",
            "description": "`true` when people already hold a recipient link to the delivery and\nthe owner accepts that they will see what the door serves at once.",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestSettings"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "patch": {
        "tags": [
          "requests"
        ],
        "summary": "Change the request's settings: any of `message`, `max_total_bytes`,\n`max_file_bytes`, `max_files`, `closes_at`, `name_rule`, `accepts`,\n`keep_zips` and `notify_arrivals`; what is left out stays. Lowering a cap\nbelow what has been received only makes the request full. Who may add files\nis not changed here: that is close, reopen and the link. A change that\nserves at once what the door held back before is refused (409), like\nmaking a request, until `?recipients_see_contributions=true`, when somebody\nalready has a link to the delivery; a change that holds as much or more is\nnot asked about.",
        "operationId": "change_request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "recipients_see_contributions",
            "in": "query",
            "description": "`true` when people already hold a recipient link to the delivery and\nthe owner accepts that they will see what the door serves at once.",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestSettings"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/request/close": {
      "post": {
        "tags": [
          "requests"
        ],
        "summary": "Stop taking files. Uploads already started may still finish; nothing new\nstarts. A closed request can be opened again (`/reopen`), unless an\noperator closed it.",
        "operationId": "close_request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "409": {
            "description": "It is already closed."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/request/contributors/{contributor_id}/remove": {
      "post": {
        "tags": [
          "requests"
        ],
        "summary": "Remove everything one contributor added, and stop that browser adding\nmore. It cannot be undone, and it stops one browser only: to stop everyone,\nmake a new link. The delivery's clients see no line about it (the files just\ngo); your trail records it. Refused (409) once it was done, and while the\ndelivery is frozen (prune the files instead).",
        "operationId": "remove_contributors_files",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "contributor_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ContributorId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContributorRemoved"
                }
              }
            }
          },
          "409": {
            "description": "Already removed, or the delivery is frozen."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/request/link": {
      "post": {
        "tags": [
          "requests"
        ],
        "summary": "Stop this link and make a new one: the answer carries the new link, and\nevery older link answers 404 from now on, for everyone, contributors who\nalready joined included. Open or closed stays as it is, and what was sent\nstays. A contributor's own token is not tied to a link: it works again\nwith the new one, so people who already joined carry on (tests/file_requests/\ntokens.rs pins it; the owner's lever for one person is removing their files).",
        "operationId": "rotate_link",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/request/reopen": {
      "post": {
        "tags": [
          "requests"
        ],
        "summary": "Take files again, until the closing date. Refused (409) once Theirway\nclosed the request, and while the delivery is deleted.",
        "operationId": "reopen_request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnerRequest"
                }
              }
            }
          },
          "409": {
            "description": "Theirway closed it, or it is open already."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "requests:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/restore": {
      "post": {
        "tags": [
          "deliveries"
        ],
        "summary": "Restore a deleted delivery: its links work again and its files count\ntoward your storage again. Only a deleted delivery can be restored: not\none that is being erased or was erased, not one that Theirway removed\n(`removed-by-theirway`), and not one that would take you over your\nstorage limit (erase something first).",
        "operationId": "restore_delivery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryDetail"
                }
              }
            }
          },
          "409": {
            "description": "The delivery is not deleted, is being erased or was erased, or restoring it would take you over your storage limit: \"There isn't room to restore this. Erase something first.\" A delivery Theirway removed answers with its own type, `removed-by-theirway`: \"Theirway removed this delivery. Contact us if you think that was a mistake.\" Erasing it is still allowed."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/snapshots": {
      "get": {
        "tags": [
          "snapshots"
        ],
        "summary": "The snapshots made from this delivery: tag, date, files, size, checksum\nand state, newest first. An empty list for a delivery nothing was made\nfrom.",
        "operationId": "list_snapshots",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotList"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "snapshots"
        ],
        "summary": "Freeze chosen files of a delivery you keep up to date as a snapshot: a\ndelivery of its own, under a tag, whose files never change and whose list\n(SHA256SUMS) and its checksum are fixed. Nothing is copied or uploaded\nand it costs no storage. Send an `Idempotency-Key` so a retry answers the\nsame. All or none: a file that cannot go in (retracted, removed, no\nchecksum you vouch for, a path the client's zip would spell differently\nor that another file shares once case is ignored, or no longer in the\ndelivery) answers 409 `snapshot-refused` with every such file and why.",
        "operationId": "make_snapshot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Any unique string, e.g. a UUID; a retry with the same key and body returns the original response.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MakeSnapshot"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotMade"
                }
              }
            }
          },
          "400": {
            "description": "No files, or more than 10,000."
          },
          "409": {
            "description": "Not a delivery you keep up to date, or the tag is used (tags ignore case, and a used tag stays reserved), or some files cannot go in (`snapshot-refused`, with every one of them and why)."
          },
          "422": {
            "description": "The tag or the note breaks its rule."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/trail": {
      "get": {
        "tags": [
          "deliveries"
        ],
        "summary": "The delivery's trail, newest first: its changes of mode and its changes to\nits files, merged. Read it with `deliveries:read`; it is the owner's alone.",
        "operationId": "get_trail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "`next` from the previous page; leave out for the first page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Rows per page, 1 to 200. Default 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrailPage"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/uploads": {
      "get": {
        "tags": [
          "uploads"
        ],
        "summary": "The uploads of this delivery that started and did not finish. Start the\nsame upload again (`POST .../uploads` with the same `relative_path`,\n`size` and `sha256`) and it resumes where storage left off.",
        "operationId": "list_interrupted",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Must be `in_progress`.",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which uploads to list. Only `in_progress` today; a value of its own so\nthat asking for anything else is refused instead of answered wrongly.",
              "enum": [
                "in_progress"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterruptedUploads"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "post": {
        "tags": [
          "uploads"
        ],
        "summary": "Start uploading one file: returns the `uploadId` and `key` every later\ncall for it needs. File bytes never pass through this API; they go to\nthe part URLs below, straight to storage. Content you already store\n(same `sha256` and `size`) answers 409 of type `conflict`: attach it with\n`POST /deliveries/{id}/files` instead. A delivery that is deleted, being\nerased or erased answers 409 of type `delivery-not-writable`: nothing can\nbe added to it (restore it first, if it is only deleted). An upload that\nwould take the account over its quota answers 413.",
        "operationId": "create_upload",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Any unique string, e.g. a UUID; a retry with the same key and body returns the original upload.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUploadRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUploadResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/uploads/{upload_id}": {
      "get": {
        "tags": [
          "uploads"
        ],
        "summary": "The parts storage already has, to resume an interrupted upload.",
        "operationId": "list_parts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "upload_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UploadId"
            }
          },
          {
            "name": "key",
            "in": "query",
            "description": "The `key` the create call returned.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PartInfo"
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      },
      "delete": {
        "tags": [
          "uploads"
        ],
        "summary": "Give up on an upload: storage drops the parts sent so far.",
        "operationId": "abort_upload",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "upload_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UploadId"
            }
          },
          {
            "name": "key",
            "in": "query",
            "description": "The `key` the create call returned.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The upload is aborted."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/uploads/{upload_id}/complete": {
      "post": {
        "tags": [
          "uploads"
        ],
        "summary": "Finish an upload once every part is PUT. The file then shows up in the\ndelivery -- if its size matches the one declared when it was created.",
        "operationId": "complete_upload",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "upload_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UploadId"
            }
          },
          {
            "name": "key",
            "in": "query",
            "description": "The `key` the create call returned.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "The file is in the delivery. The answer has no body; the file's id is in the header.",
            "headers": {
              "Theirway-File-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "The id of the file this upload made, as `GET /deliveries/{id}/files` lists it."
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/deliveries/{id}/uploads/{upload_id}/parts/{n}": {
      "get": {
        "tags": [
          "uploads"
        ],
        "summary": "A presigned URL for one part. Parts are 5 MiB or more, except the last;\na file under 5 MiB is a single part.",
        "operationId": "sign_part",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DeliveryId"
            }
          },
          {
            "name": "upload_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UploadId"
            }
          },
          {
            "name": "n",
            "in": "path",
            "description": "The part number, from 1.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "key",
            "in": "query",
            "description": "The `key` the create call returned.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignPartResponse"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "deliveries:write"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/me": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Who this credential acts for and what it may do.",
        "operationId": "me",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "account:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    },
    "/me/avatar": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "The signed-in producer's own picture, from Gravatar, if they have one.",
        "operationId": "my_avatar",
        "responses": {
          "200": {
            "description": "The picture: image/jpeg, image/png, image/webp or image/gif.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0
                  }
                }
              }
            }
          },
          "404": {
            "description": "No picture: none exists, or avatars are switched off."
          },
          "4XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "5XX": {
            "description": "A problem: `type` says which, `detail` says what to do next.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "access_token": [
              "account:read"
            ]
          },
          {
            "session_cookie": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Accepts": {
        "type": "string",
        "description": "What a request takes.",
        "enum": [
          "photos_and_videos",
          "any"
        ]
      },
      "AccessTokenId": {
        "type": "string",
        "format": "uuid"
      },
      "AddAddressRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "The address to email this link to. Final: it cannot be changed."
          }
        }
      },
      "AddAddressResponse": {
        "type": "object",
        "required": [
          "id",
          "email"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "id": {
            "$ref": "#/components/schemas/RecipientId"
          }
        }
      },
      "Applied": {
        "type": "object",
        "description": "What `apply` did.",
        "required": [
          "mode",
          "changed"
        ],
        "properties": {
          "changed": {
            "type": "boolean",
            "description": "False when it already had it, and nothing was written."
          },
          "mode": {
            "$ref": "#/components/schemas/Mode",
            "description": "The mode the delivery has now."
          }
        }
      },
      "AttachRequest": {
        "type": "object",
        "required": [
          "stored_file_id",
          "name",
          "relative_path"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "At most 1024 bytes (else 422)."
          },
          "relative_path": {
            "$ref": "#/components/schemas/RelativePath",
            "description": "Where the file sits in this delivery's folder tree; the same rules as\nfor an upload (`POST .../uploads`)."
          },
          "stored_file_id": {
            "$ref": "#/components/schemas/StoredFileId",
            "description": "From `POST .../files/lookup`, or a file in another of your deliveries."
          }
        }
      },
      "By": {
        "type": "string",
        "description": "Who makes a move, and who closed a request. Stored in `closed_by` and in\nthe audit rows (`file_request_state_changes.by`).",
        "enum": [
          "owner",
          "operator"
        ]
      },
      "CompletePart": {
        "type": "object",
        "required": [
          "PartNumber",
          "ETag"
        ],
        "properties": {
          "ETag": {
            "type": "string"
          },
          "PartNumber": {
            "type": "integer",
            "format": "int32"
          }
        }
      },
      "CompleteRequest": {
        "type": "object",
        "required": [
          "parts"
        ],
        "properties": {
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompletePart"
            },
            "description": "Every part, with the `ETag` storage answered its PUT with."
          }
        }
      },
      "ContributorId": {
        "type": "string",
        "format": "uuid"
      },
      "ContributorRef": {
        "type": "object",
        "description": "Who sent a file that came in through a file request (`null` on the\nowner's own files). Shared with the paged list (files.rs).",
        "required": [
          "id",
          "folder"
        ],
        "properties": {
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "What they called themselves, if they did."
          },
          "folder": {
            "type": "string",
            "description": "The folder their files are in, \"Contributor 3\" when they gave no name."
          },
          "id": {
            "$ref": "#/components/schemas/ContributorId"
          }
        }
      },
      "ContributorRemoved": {
        "type": "object",
        "required": [
          "files_removed"
        ],
        "properties": {
          "files_removed": {
            "type": "integer",
            "format": "int64",
            "description": "How many files the removal took out of the delivery."
          }
        }
      },
      "ContributorSummary": {
        "type": "object",
        "description": "What one contributor has sent, for the owner's list.",
        "required": [
          "id",
          "folder",
          "files",
          "bytes",
          "held"
        ],
        "properties": {
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "What they called themselves, if they did."
          },
          "files": {
            "type": "integer",
            "format": "int64"
          },
          "first_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "folder": {
            "type": "string",
            "description": "Where their files are in the delivery."
          },
          "held": {
            "type": "integer",
            "format": "int64",
            "description": "Of `files`, how many wait for the owner's release."
          },
          "id": {
            "$ref": "#/components/schemas/ContributorId"
          },
          "last_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "removed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the owner removed everything they added (contributor_removal.rs);\n`null` while they are joined. A removed one shows 0 files."
          }
        }
      },
      "CreateDelivery": {
        "type": "object",
        "required": [
          "title",
          "client_name"
        ],
        "properties": {
          "client_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "client_name": {
            "type": "string",
            "description": "Who receives it, as the producer calls them."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Release notes for the client's page: plain text, at most 10,000\ncharacters. Leave out for none; `PUT .../description` changes them."
          },
          "options": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/OptionsRequest",
                "description": "Options to start with; leave out for none (every rail off)."
              },
              {
                "type": "null"
              }
            ]
          },
          "presentation": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Presentation",
                "description": "How the delivery is drawn: `\"pictures\"` (the default) or `\"files\"`.\nChosen now and never changed."
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "type": "string",
            "description": "What the delivery is, e.g. \"Wedding, 12 September\"."
          }
        }
      },
      "CreateRecipientRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreateRecipientResponse": {
        "type": "object",
        "required": [
          "id",
          "link"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/RecipientId"
          },
          "link": {
            "type": "string",
            "description": "Send this to the recipient: it opens their download page. Anyone\nholding it can download the delivery's files."
          }
        }
      },
      "CreateUploadRequest": {
        "type": "object",
        "required": [
          "filename",
          "type",
          "size",
          "relative_path"
        ],
        "properties": {
          "filename": {
            "type": "string"
          },
          "relative_path": {
            "$ref": "#/components/schemas/RelativePath",
            "description": "Where the file sits in the delivery's folder tree, e.g.\n`raw/IMG_0001.CR3`; the filename alone for a flat delivery. Folders\nare separated by `/`; no empty, `.` or `..` part, no leading `/` or\ndrive letter, no backslash or control characters, at most 1024 bytes\n(else 422). `filename` is held to the same 1024 bytes."
          },
          "sha256": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Sha256Hex",
                "description": "The SHA-256 of the whole file, 64 lowercase hex characters, computed\nby the browser. With it, content you already store is answered with\na 409 (attach it instead) and starting the same upload again resumes\nthe first. Without it the file is stored on its own and never reused."
              },
              {
                "type": "null"
              }
            ]
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "The exact size in bytes; completing fails if the parts add up to\nanything else."
          },
          "type": {
            "type": "string",
            "description": "The file's media type, e.g. `image/jpeg`."
          }
        }
      },
      "CreateUploadResponse": {
        "type": "object",
        "required": [
          "uploadId",
          "key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Pass back as `?key=` on every later call for this upload."
          },
          "uploadId": {
            "$ref": "#/components/schemas/UploadId"
          }
        }
      },
      "DeletedBy": {
        "type": "string",
        "description": "Who removed a delivery: the producer (their own delete, or an erase an\noperator ran for them with `deliveries erase --force-now`) or an operator\n(a takedown after a report, abuse/, and nothing else). Stored in\n`deliveries.deleted_by`,\nchecked by migration 0029; null while the delivery is active. Shown to the\nproducer (so the app can say it) and to the client (`removed_by` in the\n410), and the reason a restore is refused.",
        "enum": [
          "producer",
          "operator"
        ]
      },
      "DeletedResponse": {
        "type": "object",
        "required": [
          "state",
          "deleted_at",
          "erase_after"
        ],
        "properties": {
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          },
          "erase_after": {
            "type": "string",
            "format": "date-time",
            "description": "When it will be erased if you do not restore it first."
          },
          "state": {
            "$ref": "#/components/schemas/DeliveryState"
          }
        }
      },
      "Delivery": {
        "allOf": [
          {
            "type": "object",
            "description": "The lifecycle half of a delivery as the API shows it: the state, and\nthe dates that go with it. Flattened into the delivery's detail and into\neach item of the list.",
            "required": [
              "state"
            ],
            "properties": {
              "days_left": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "While `deleted`: whole days left to restore it, rounded up: 1 through\nthe last day, 0 once the 30 days are over and the erasing is due."
              },
              "deleted_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When the producer deleted it; `null` while it is active."
              },
              "deleted_by": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DeletedBy",
                    "description": "Who deleted it: `producer` (you) or `operator` (Theirway removed it\nafter a report: it cannot be restored, only erased, and the app should\nsay so); `null` while it is active. Kept when it is erased."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "erase_after": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "While `deleted`: when it will be erased if nobody restores it."
              },
              "erase_requested_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "erased_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "state": {
                "$ref": "#/components/schemas/DeliveryState"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "id",
              "title",
              "client_name",
              "created_at",
              "options",
              "presentation",
              "description"
            ],
            "properties": {
              "client_email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "client_name": {
                "type": "string"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "description": {
                "$ref": "#/components/schemas/Description",
                "description": "The release notes; `\"\"` when there are none."
              },
              "id": {
                "$ref": "#/components/schemas/DeliveryId"
              },
              "options": {
                "$ref": "#/components/schemas/DeliveryOptions"
              },
              "presentation": {
                "$ref": "#/components/schemas/Presentation",
                "description": "`\"pictures\"` or `\"files\"`: how the client's page draws it."
              },
              "title": {
                "type": "string"
              }
            }
          }
        ]
      },
      "DeliveryDescription": {
        "type": "object",
        "description": "A delivery's release notes, as stored.",
        "required": [
          "description"
        ],
        "properties": {
          "description": {
            "$ref": "#/components/schemas/Description"
          }
        }
      },
      "DeliveryDetail": {
        "allOf": [
          {
            "allOf": [
              {
                "type": "object",
                "description": "The lifecycle half of a delivery as the API shows it: the state, and\nthe dates that go with it. Flattened into the delivery's detail and into\neach item of the list.",
                "required": [
                  "state"
                ],
                "properties": {
                  "days_left": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "While `deleted`: whole days left to restore it, rounded up: 1 through\nthe last day, 0 once the 30 days are over and the erasing is due."
                  },
                  "deleted_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "When the producer deleted it; `null` while it is active."
                  },
                  "deleted_by": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/DeletedBy",
                        "description": "Who deleted it: `producer` (you) or `operator` (Theirway removed it\nafter a report: it cannot be restored, only erased, and the app should\nsay so); `null` while it is active. Kept when it is erased."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "erase_after": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "While `deleted`: when it will be erased if nobody restores it."
                  },
                  "erase_requested_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "erased_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "state": {
                    "$ref": "#/components/schemas/DeliveryState"
                  }
                }
              },
              {
                "type": "object",
                "description": "`state`, and while it is deleted, when it will be erased and how many\ndays are left to restore it. A deleted delivery is read-only here."
              }
            ]
          },
          {
            "type": "object",
            "required": [
              "id",
              "title",
              "client_name",
              "created_at",
              "options",
              "presentation",
              "description",
              "mode",
              "incoming",
              "snapshots",
              "files",
              "cover_urls",
              "pruned_files",
              "removed_files",
              "account_used_bytes",
              "account_quota_bytes",
              "recipients",
              "events"
            ],
            "properties": {
              "account_quota_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "account_used_bytes": {
                "type": "integer",
                "format": "int64",
                "description": "What the whole account uses of its storage (every delivery, not only\nthis one) and the most it may use, in bytes: the figures a prune\npreview names the same way. What counts is `uploads/usage.rs`'s."
              },
              "client_email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "client_name": {
                "type": "string"
              },
              "cover_urls": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Up to three links to the thumbnails of the delivery's first files that\nhave one, in the order they were added, each valid for 15 minutes;\n`[]` when no file has a thumbnail yet, and always for a delivery that\nis deleted, being erased or erased. A file someone sent through your\nfile request is left out until you release it. The same cover as this\ndelivery's item in the list (`GET /deliveries`); thumbnails only,\nnever the file itself."
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "description": {
                "$ref": "#/components/schemas/Description",
                "description": "The release notes at the top of the client's page; `\"\"` when there\nare none (`PUT .../description`)."
              },
              "events": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EventItem"
                },
                "description": "Every event, newest first; `/deliveries/{id}/events` pages them."
              },
              "files": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DeliveryFileItem"
                }
              },
              "id": {
                "$ref": "#/components/schemas/DeliveryId"
              },
              "incoming": {
                "type": "boolean",
                "description": "Read-only, derived on every read and stored nowhere: `true` while\nthe delivery has a file request and nobody else holds a live (not\nrevoked) recipient link to it, so what arrives is yours alone. Making\na link turns it `false`. No call sets it and no rule reads it: it says\nhow the web app draws the delivery, nothing more.",
                "readOnly": true
              },
              "mode": {
                "$ref": "#/components/schemas/Mode",
                "description": "`\"one_off\"`, `\"maintained\"` or `\"frozen\"`: how the delivery is kept\n(`PUT .../mode`). A maintained delivery's page lists the newest\nfiles first. A frozen delivery is a snapshot: its files, tags, notes\nand release notes stay as they are."
              },
              "options": {
                "$ref": "#/components/schemas/DeliveryOptions",
                "description": "Off by default; the producer turns them on (`PATCH .../options`)."
              },
              "presentation": {
                "$ref": "#/components/schemas/Presentation",
                "description": "`\"pictures\"` or `\"files\"`: how the client's page draws the delivery.\nChosen when it was made."
              },
              "pruned_files": {
                "type": "integer",
                "format": "int64",
                "description": "How many files were pruned from this delivery, for good (each left a\nrecord, which a Files page draws as a line for the client,\n`POST .../files/prune`); `files` has the rest.\nThe length of `removed_files`."
              },
              "recipients": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RecipientItem"
                }
              },
              "removed_files": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RemovedFile"
                },
                "description": "Those files, newest removal first: what each was called, its size and\nSHA-256 (`null` if it had none: a file a request link brought, an\nupload that sent none, or one older than content hashes), when it was\npruned and by whom (since 2026-10-07). `[]` for an erased delivery,\nwhose records are gone with its names."
              },
              "request": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/OwnerRequest",
                    "description": "The delivery's file request, or `null` when it has none (see\n`GET /deliveries/{id}/request`). Its link only with `requests:write`."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "snapshot": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/OwnerSnapshot",
                    "description": "What makes a frozen delivery a snapshot: its tag (`null` once erased),\nwhen it was frozen, the SHA-256 of its SHA256SUMS list and the\ndelivery it was made from. `null` unless the delivery is frozen."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "snapshots": {
                "type": "integer",
                "format": "int64",
                "description": "How many snapshots this delivery has made, active or deleted: what the\ndelete and erase sheets say stay behind."
              },
              "title": {
                "type": "string"
              }
            }
          }
        ]
      },
      "DeliveryFile": {
        "type": "object",
        "required": [
          "id",
          "stored_file_id",
          "name",
          "relative_path",
          "size",
          "content_type",
          "tags",
          "note",
          "state",
          "added_at"
        ],
        "properties": {
          "added_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the file reached this delivery: when it was uploaded, sent\nthrough your file request, unpacked or attached here, which can be\nlater than when its bytes were first stored. A snapshot's files are\nthe exception: each keeps the time it reached the delivery the\nsnapshot was made from, not the time the snapshot was frozen."
          },
          "content_type": {
            "type": "string"
          },
          "contributor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContributorRef",
                "description": "Who sent it, when a contributor did (a file request); `null` for the\nowner's own files. The client does not see it, only the folder."
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "This delivery's reference; what removing and downloading name."
          },
          "name": {
            "type": "string"
          },
          "note": {
            "$ref": "#/components/schemas/Note",
            "description": "The producer's caption for this file in this delivery; `\"\"` when\nthere is none. The client sees it too."
          },
          "relative_path": {
            "type": "string"
          },
          "removed_by_theirway_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When Theirway took the file's bytes down after a report; `null`\notherwise. A takedown reaches every delivery that holds the same\nstored file, so this can be set on a file you never retracted: your\nclient gets a 410 `file-removed` for it, and you cannot reinstate it.\nIndependent of `state`."
          },
          "retracted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it was retracted; `null` while available."
          },
          "retraction_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the client is told; `null` while available."
          },
          "sha256": {
            "type": [
              "string",
              "null"
            ],
            "description": "The SHA-256 your client is shown: the one your upload reported (your\nbrowser, or a tool calling this API), or the one Theirway computed for\nan entry of an unpacked zip or a file someone sent you through a\nrequest; `null` for an upload that sent none, for files uploaded\nbefore content hashes were kept, and for a file someone sent you until\nTheirway has computed its hash."
          },
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "state": {
            "$ref": "#/components/schemas/FileState",
            "description": "`available`; `retracted`: the client has no download of it, and reads\nthe reason below (`POST .../files/retract`, `.../reinstate`); or\n`held`: someone sent it through a request that takes any file, and\nnobody you sent this delivery to can see it until you release it\n(`POST .../files/release`; `GET .../files/{id}/download` to look\nfirst)."
          },
          "stored_file_id": {
            "$ref": "#/components/schemas/StoredFileId",
            "description": "The stored file it points at, to attach it to another delivery."
          },
          "tags": {
            "$ref": "#/components/schemas/Tags",
            "description": "The producer's labels for this file in this delivery, in their order;\n`[]` when there are none. The client sees them too."
          },
          "thumbnail_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "A link to show the thumbnail, valid for 15 minutes; `null` until the\nbrowser has uploaded one."
          },
          "unpack": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/FileUnpackView",
                "description": "The latest unpacking of this file, when you pressed Unpack on it\n(`POST .../files/{id}/unpack`); `null` for a file never unpacked."
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "DeliveryFileItem": {
        "type": "object",
        "required": [
          "id",
          "name",
          "relative_path",
          "size",
          "tags",
          "note",
          "state",
          "added_at"
        ],
        "properties": {
          "added_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the file reached this delivery; in a snapshot, when it reached\nthe delivery the snapshot was made from (see `DeliveryFile` in\nfiles.rs)."
          },
          "contributor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContributorRef",
                "description": "Who sent it, when a contributor did; `null` for your own files."
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "note": {
            "$ref": "#/components/schemas/Note",
            "description": "The producer's caption for this file; `\"\"` when there is none."
          },
          "relative_path": {
            "type": "string"
          },
          "removed_by_theirway_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When Theirway took the file's bytes down after a report; `null`\notherwise (see `DeliveryFile` in files.rs)."
          },
          "retracted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it was retracted; `null` while available."
          },
          "retraction_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the client is told; `null` while available."
          },
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "state": {
            "$ref": "#/components/schemas/FileState",
            "description": "`available`, or `retracted` (the client has no download of it and\nreads the reason below)."
          },
          "tags": {
            "$ref": "#/components/schemas/Tags",
            "description": "The producer's labels for this file; `[]` when there are none."
          },
          "unpack": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/FileUnpackView",
                "description": "The latest unpacking of this file, when you pressed Unpack on it\n(`POST .../files/{id}/unpack`); `null` for a file never unpacked."
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "DeliveryId": {
        "type": "string",
        "format": "uuid"
      },
      "DeliveryListItem": {
        "allOf": [
          {
            "type": "object",
            "description": "The lifecycle half of a delivery as the API shows it: the state, and\nthe dates that go with it. Flattened into the delivery's detail and into\neach item of the list.",
            "required": [
              "state"
            ],
            "properties": {
              "days_left": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "While `deleted`: whole days left to restore it, rounded up: 1 through\nthe last day, 0 once the 30 days are over and the erasing is due."
              },
              "deleted_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When the producer deleted it; `null` while it is active."
              },
              "deleted_by": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/DeletedBy",
                    "description": "Who deleted it: `producer` (you) or `operator` (Theirway removed it\nafter a report: it cannot be restored, only erased, and the app should\nsay so); `null` while it is active. Kept when it is erased."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "erase_after": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "While `deleted`: when it will be erased if nobody restores it."
              },
              "erase_requested_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "erased_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "state": {
                "$ref": "#/components/schemas/DeliveryState"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "id",
              "title",
              "client_name",
              "created_at",
              "file_count",
              "total_bytes",
              "options",
              "presentation",
              "description",
              "mode",
              "incoming",
              "cover_urls"
            ],
            "properties": {
              "client_email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "client_name": {
                "type": "string"
              },
              "cover_urls": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Up to three links to thumbnails of the delivery's first files that\nhave one, in the order they were added, each valid for 15 minutes;\n`[]` when no file has a thumbnail yet, and always for a deleted\ndelivery. A file someone sent through your file request is left\nout until you release it. Thumbnails only, never the file itself."
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "description": {
                "$ref": "#/components/schemas/Description",
                "description": "The release notes; `\"\"` when there are none."
              },
              "file_count": {
                "type": "integer",
                "format": "int64"
              },
              "id": {
                "$ref": "#/components/schemas/DeliveryId"
              },
              "incoming": {
                "type": "boolean",
                "description": "Read-only, derived on every read and stored nowhere: `true` while\nthe delivery has a file request and nobody else holds a live (not\nrevoked) recipient link to it. The same as the delivery's own\n`incoming` (`GET /deliveries/{id}`); no call sets it and no rule reads\nit.",
                "readOnly": true
              },
              "mode": {
                "$ref": "#/components/schemas/Mode",
                "description": "`\"one_off\"`, `\"maintained\"` or `\"frozen\"` (a snapshot): how the\ndelivery is kept."
              },
              "options": {
                "$ref": "#/components/schemas/DeliveryOptions"
              },
              "presentation": {
                "$ref": "#/components/schemas/Presentation",
                "description": "`\"pictures\"` or `\"files\"`: how the client's page draws the delivery."
              },
              "request": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ListedRequest",
                    "description": "The delivery's file request in four figures (what it is doing, how many\nfiles came, from how many people, how many of them wait for your\nrelease), or `null` when it has none."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "title": {
                "type": "string"
              },
              "total_bytes": {
                "type": "integer",
                "format": "int64"
              }
            }
          }
        ]
      },
      "DeliveryOptions": {
        "type": "object",
        "description": "A delivery's options, as the producer reads them back.",
        "required": [
          "push_rails"
        ],
        "properties": {
          "push_rails": {
            "$ref": "#/components/schemas/PushRails"
          }
        }
      },
      "DeliveryPage": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeliveryListItem"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` for the next page; `null` on the last one."
          }
        }
      },
      "DeliveryState": {
        "type": "string",
        "description": "Where a delivery is in its life. Stored as text in `deliveries.state`,\nchecked by migration 0028.",
        "enum": [
          "active",
          "deleted",
          "erasing",
          "erased"
        ]
      },
      "Description": {
        "type": "string",
        "description": "A delivery's release notes: trimmed, in Unicode normal form C, at most\n10,000 characters, newlines as `\\n`. Empty means no notes, the default,\nand is how they are cleared."
      },
      "DescriptionRequest": {
        "type": "object",
        "description": "What a producer sends: the whole release notes.",
        "required": [
          "description"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Plain text, at most 10,000 characters; newlines and tabs are kept.\nEmpty clears the notes."
          }
        }
      },
      "DownloadLinksRequest": {
        "type": "object",
        "required": [
          "file_ids"
        ],
        "properties": {
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to sign links for, 1 to 200."
          }
        },
        "additionalProperties": false
      },
      "EditFileRequest": {
        "type": "object",
        "properties": {
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Replaces the file's note (at most 2000 characters, newlines allowed).\n`\"\"` clears it. Leave out, or `null`, to keep it."
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Replaces the file's tags (at most 20, each 1 to 40 characters, no\ncomma, no leading `#`; repeats in any case are dropped). `[]` removes\nthem all. Leave out, or `null`, to keep what the file has."
          }
        },
        "additionalProperties": false
      },
      "EditFilesRequest": {
        "type": "object",
        "required": [
          "file_ids"
        ],
        "properties": {
          "add_tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Tags to put on each file, after the ones it has. A tag a file already\nhas, in any case, is left as it is."
          },
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to change, 1 to 500, all of this delivery."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Replaces each file's note. `\"\"` clears it. Leave out to keep them."
          },
          "remove_tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Tags to take off each file, matched without regard to case. Taken off\nfirst, so a tag in both lists ends up spelt as in `add_tags`."
          }
        },
        "additionalProperties": false
      },
      "EmailPreview": {
        "type": "object",
        "required": [
          "from",
          "reply_to",
          "to",
          "subject",
          "text",
          "may_send"
        ],
        "properties": {
          "from": {
            "type": "string",
            "description": "`Theirway <delivery@theirway.app>`, or `Anna Berg via Theirway\n<delivery@theirway.app>` when you have set a sender name\n(`PUT /api/me/sender-name`)."
          },
          "last_sent_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this link was last handed over to the mail service."
          },
          "may_send": {
            "type": "boolean",
            "description": "Whether the send would pass the rules about you and this link. It\nnever says anything about the address itself (whether it asked us to\nstop, or was emailed by others): only sending can."
          },
          "notice": {
            "type": [
              "string",
              "null"
            ]
          },
          "reply_to": {
            "type": "string",
            "description": "Your account address: where the client's reply goes."
          },
          "retry_after": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Set while this send is refused until a known moment: the link's\ncooldown, or the producer's hour or day cap."
          },
          "sender_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The sender name you have set now, or `null`: the one `PUT\n/api/me/sender-name` changes. Not always the one in `from`: a retry of\nan email that may not have gone out shows the name that email was\nclaimed with, so the second try is the same email."
          },
          "subject": {
            "type": "string"
          },
          "text": {
            "type": "string",
            "description": "The plain-text part, link included. The stop code in its last lines\nis a stand-in until the email is sent."
          },
          "to": {
            "type": "string"
          }
        }
      },
      "ErasingResponse": {
        "type": "object",
        "required": [
          "state",
          "erase_requested_at",
          "snapshots_kept"
        ],
        "properties": {
          "erase_requested_at": {
            "type": "string",
            "format": "date-time"
          },
          "erased_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Only once `erased`."
          },
          "snapshots_kept": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeptSnapshot"
            },
            "description": "The snapshots made from this delivery that are still there, active or\ndeleted. None is erased with it: each keeps the client's name, address,\nrelease notes and files until erased too (`POST .../erase` on its id)."
          },
          "state": {
            "$ref": "#/components/schemas/DeliveryState",
            "description": "`erasing`, or `erased` when the erasing already finished."
          }
        }
      },
      "EventItem": {
        "type": "object",
        "description": "Something that happened to a delivery; `type` says what. Also part of\ndetail.rs's view.",
        "required": [
          "id",
          "type",
          "data",
          "at",
          "count",
          "last_at"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When it first happened."
          },
          "count": {
            "type": "integer",
            "format": "int32",
            "description": "How many times it happened: 1, except for `opened` (2026-10-07), where\nloads of the client's page within 30 minutes of each other are one\nevent that counts them (recipient_portal/opens.rs)."
          },
          "data": {
            "type": "object",
            "description": "Depends on `type`, e.g. `{ \"name\": ..., \"size\": ... }` for an upload.\n`download_started` holds `{ \"file_count\": ... }` (or a `file_id`);\n`downloaded` holds `{ \"count\", \"bytes\", \"method\": \"zip\" or \"files\" }`,\nor nothing. The download numbers are the client's own word: the\nfiles go from storage to the browser without passing this API.\n`transfer_created` holds `{ \"file_count\", \"bytes\" }` (the client asked\nfor the files to be sent to a server of their own) and\n`transfer_done` holds `{ \"files_done\", \"files_failed\", \"bytes\" }`:\ncounts only, never the destination.\n`link_email_bounced` holds `{}`: an email Theirway sent to this link's\naddress could not be delivered; `recipient_id` is the link, and the\naddress is never in it.\n`contributor_removed` holds `{ \"file_count\": 42 }`: the owner removed\neverything one contributor added (file_requests/contributor_removal.rs);\na count, never the contributor's name.\n`push_rail_enabled` and `push_rail_disabled` hold `{ \"rail\": \"sftp\" }`\n(or `\"s3\"`): the producer turned that rail on or off."
          },
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "last_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it last happened; the same as `at` when `count` is 1."
          },
          "recipient_id": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecipientId"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "$ref": "#/components/schemas/EventKind",
            "description": "Read back as the row holds it, so a kind written long ago still\nreads; the document's list is the kinds written today."
          }
        }
      },
      "EventKind": {
        "type": "string",
        "description": "What happened to a delivery. `as_str` is the spelling stored in\n`events.type`.",
        "enum": [
          "file_uploaded",
          "file_removed",
          "contributor_removed",
          "opened",
          "download_started",
          "downloaded",
          "transfer_created",
          "transfer_done",
          "link_email_bounced",
          "push_rail_enabled",
          "push_rail_disabled"
        ]
      },
      "EventPage": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventItem"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` for the next page; `null` on the last one."
          }
        }
      },
      "Failure": {
        "type": "string",
        "description": "Why a send is `refused` or `uncertain`. Fixed words, no provider text.",
        "enum": [
          "provider_refused",
          "provider_unreachable",
          "interrupted",
          "address_refused"
        ]
      },
      "FilePage": {
        "type": "object",
        "required": [
          "files",
          "total"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeliveryFile"
            }
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `after` for the next page; `null` on the last one."
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "Every file in the delivery, not only this page."
          }
        }
      },
      "FileRequestState": {
        "type": "string",
        "description": "Where a request is. Stored as text in `file_requests.state`, checked by\nmigration 0031.",
        "enum": [
          "open",
          "closed"
        ]
      },
      "FileState": {
        "type": "string",
        "description": "Whether a file can be had. Stored as text in `delivery_files.state`, added\nby the migration `*_file_availability.sql`; the producer sees it on every\nfile of the delivery's detail.\n\n`Held` (migration `*_request_accepts.sql`, package K) is a contribution\nnothing has vouched for: the owner sees and downloads it, no client reader\nlists, counts or signs it, until the owner releases it.",
        "enum": [
          "available",
          "retracted",
          "held"
        ]
      },
      "FileUnpackView": {
        "type": "object",
        "description": "What a producer's zip file shows of its latest job.",
        "required": [
          "state",
          "added",
          "left_out",
          "total",
          "words"
        ],
        "properties": {
          "added": {
            "type": "integer",
            "format": "int32"
          },
          "left_out": {
            "type": "integer",
            "format": "int32"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "total": {
            "type": "integer",
            "format": "int32",
            "description": "As for a stranger's zip (`unpacking`): added so far plus still to come."
          },
          "words": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FilesUpdated": {
        "type": "object",
        "required": [
          "updated"
        ],
        "properties": {
          "updated": {
            "type": "integer",
            "description": "How many distinct files the call applied to.",
            "minimum": 0
          }
        }
      },
      "FoundFile": {
        "type": "object",
        "required": [
          "sha256",
          "stored_file_id"
        ],
        "properties": {
          "sha256": {
            "type": "string"
          },
          "stored_file_id": {
            "$ref": "#/components/schemas/StoredFileId"
          }
        }
      },
      "Holder": {
        "type": "object",
        "description": "Another active delivery that holds the same stored file.",
        "required": [
          "id",
          "title"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId"
          },
          "title": {
            "type": "string"
          }
        }
      },
      "InterruptedUpload": {
        "type": "object",
        "required": [
          "relative_path",
          "size",
          "sha256",
          "created_at"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the upload was started, UTC."
          },
          "relative_path": {
            "type": "string"
          },
          "sha256": {
            "type": "string",
            "description": "The SHA-256 the browser reported for the whole file."
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes, as declared when the upload started."
          }
        }
      },
      "InterruptedUploads": {
        "type": "object",
        "required": [
          "uploads",
          "total"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "Every interrupted upload of the delivery, not only those listed."
          },
          "uploads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InterruptedUpload"
            },
            "description": "Up to 500, ordered by path."
          }
        }
      },
      "JobState": {
        "type": "string",
        "enum": [
          "queued",
          "running",
          "done",
          "partial",
          "failed"
        ]
      },
      "JobView": {
        "type": "object",
        "required": [
          "job_id",
          "name",
          "state",
          "added",
          "left_out",
          "total",
          "words"
        ],
        "properties": {
          "added": {
            "type": "integer",
            "format": "int32",
            "description": "Files added to the delivery so far."
          },
          "contributor_id": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContributorId",
                "description": "Who sent the zip; only the owner is told."
              },
              {
                "type": "null"
              }
            ]
          },
          "job_id": {
            "$ref": "#/components/schemas/UnpackJobId"
          },
          "left_out": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "description": "The zip's name."
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "total": {
            "type": "integer",
            "format": "int32",
            "description": "The files it will have added when it ends, as far as is known: those\nadded so far and those still to come. 0 until the plan is in, and\n`added` once it has ended. (A file that fails on the way leaves this\nnumber, so it can fall by one; it never promises more than will come.)"
          },
          "words": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Why it failed, or what was left out, in sentences."
          }
        }
      },
      "Kept": {
        "type": "object",
        "description": "A file that pruning would NOT free, and where it would stay.",
        "required": [
          "file_id",
          "also_in"
        ],
        "properties": {
          "also_in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Holder"
            }
          },
          "file_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "KeptSnapshot": {
        "type": "object",
        "description": "A snapshot that keeps what its source's erasure would not take.",
        "required": [
          "id",
          "tag",
          "state"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId"
          },
          "state": {
            "$ref": "#/components/schemas/DeliveryState"
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "Left": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Member"
          },
          {
            "type": "object",
            "required": [
              "file_id",
              "reason"
            ],
            "properties": {
              "file_id": {
                "type": "string",
                "format": "uuid"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        ],
        "description": "A reference that a reinstatement everywhere left retracted, with the reason\nit is retracted for."
      },
      "LinkEmailItem": {
        "type": "object",
        "description": "The latest email of one link, for its owner. \"Emailed\" means HANDED OVER to\nthe mail service, which is not \"delivered\": a message can still bounce.",
        "required": [
          "state",
          "at"
        ],
        "properties": {
          "arrival": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ShownArrival",
                "description": "What the mail service reported after it took a `sent` email, or `null`\n(nothing reported yet, or Theirway is not set up to hear it). `state`\nand `at` are untouched by it: `sent` still means handed over."
              },
              {
                "type": "null"
              }
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When it last changed state: when it was handed over, refused, or\nstarted."
          },
          "failure": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Failure",
                "description": "Why it is `refused` or `uncertain`. `address_refused` means Theirway\ncould not email this address (and says no more than that)."
              },
              {
                "type": "null"
              }
            ]
          },
          "reply_forwarded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When Theirway took in the newest reply to this email and passed it on\nto the producer (reply_relay/; the time of the taking-in, a minute\nafter the client wrote, not of the passing-on), or `null` when none\nwas. A time and nothing of what the reply said.\nFilled in by deliveries/detail.rs from reply_relay/, which owns that\ntable; this module only names the send to ask about."
          },
          "state": {
            "$ref": "#/components/schemas/LinkEmailState"
          }
        }
      },
      "LinkEmailState": {
        "type": "string",
        "enum": [
          "sending",
          "sent",
          "refused",
          "uncertain"
        ]
      },
      "LinkItem": {
        "type": "object",
        "description": "One link of a snapshot and what its holder did with it.",
        "required": [
          "recipient_id",
          "revoked",
          "opens"
        ],
        "properties": {
          "download_started_last_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The latest time download links were signed for this link's holder."
          },
          "downloaded": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Reported",
                "description": "The page's latest report that it downloaded; `null` if none."
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The label you gave the person; `null` for a link made without one."
          },
          "opened_first_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the page was first loaded through the link; `null` if never."
          },
          "opened_last_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "opens": {
            "type": "integer",
            "format": "int64",
            "description": "How many times it was loaded; loads within 30 minutes of each other\ncount once."
          },
          "recipient_id": {
            "$ref": "#/components/schemas/RecipientId"
          },
          "revoked": {
            "type": "boolean"
          }
        }
      },
      "ListedRequest": {
        "type": "object",
        "description": "The request of a listed delivery, in the figures the card shows.",
        "required": [
          "standing",
          "files_received",
          "people",
          "held"
        ],
        "properties": {
          "files_received": {
            "type": "integer",
            "format": "int32"
          },
          "held": {
            "type": "integer",
            "format": "int64",
            "description": "Files of this delivery that nobody can see until the owner releases them."
          },
          "people": {
            "type": "integer",
            "format": "int64"
          },
          "standing": {
            "$ref": "#/components/schemas/Standing"
          }
        }
      },
      "LookupFile": {
        "type": "object",
        "required": [
          "sha256",
          "size"
        ],
        "properties": {
          "sha256": {
            "$ref": "#/components/schemas/Sha256Hex"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "The file's size in bytes; a stored file only matches when both agree."
          }
        }
      },
      "LookupRequest": {
        "type": "object",
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LookupFile"
            },
            "description": "At most 500."
          }
        }
      },
      "LookupResponse": {
        "type": "object",
        "required": [
          "found"
        ],
        "properties": {
          "found": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FoundFile"
            },
            "description": "The entries you already have stored; leave out of the upload the\nones listed here and attach them instead."
          }
        }
      },
      "MailSendId": {
        "type": "string",
        "format": "uuid"
      },
      "MakeSnapshot": {
        "type": "object",
        "required": [
          "tag",
          "file_ids"
        ],
        "properties": {
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to freeze, 1 to 10,000, all of this delivery."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "The release notes of the snapshot (plain text, at most 10,000\ncharacters); leave out for none."
          },
          "tag": {
            "type": "string",
            "description": "The one name this snapshot is known by, such as `v2.4.1`: 1 to 40\ncharacters, no comma, no leading `#`, no control or invisible\ncharacter. Never used twice among the snapshots of one delivery,\nignoring case, and never moved: a used tag stays reserved, even after\nthe snapshot is erased."
          }
        },
        "additionalProperties": false
      },
      "Me": {
        "type": "object",
        "required": [
          "id",
          "email",
          "credential",
          "scopes",
          "role",
          "arrival_notices_available"
        ],
        "properties": {
          "arrival_notices_available": {
            "type": "boolean",
            "description": "Whether this deployment can email an owner when files arrive on their\nfile request (`notify_arrivals`), which the sheet that makes a request\nmust know before the request exists to offer the choice. The request's\nown view says the same as `notify_arrivals_available`."
          },
          "credential": {
            "type": "string",
            "description": "How this request signed in: `session` or `access_token`."
          },
          "email": {
            "type": "string"
          },
          "has_avatar": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the account has a picture, as far as is known without asking\nGravatar: `true`, `false`, or `null` (not looked up yet, or due: ask\n`GET /me/avatar`). A page that gets `false` draws initials and asks\nfor nothing, so no 404 reaches the console."
          },
          "id": {
            "$ref": "#/components/schemas/ProducerId"
          },
          "role": {
            "$ref": "#/components/schemas/Role",
            "description": "The account's role right now: `producer` or `superuser`. A token\nreports its producer's role but gains no scope from it."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What this credential may do, e.g. `deliveries:read`."
          },
          "sender_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The name link emails show in their From (\"Anna Berg via Theirway\"), or\n`null` when none is set and the From says \"Theirway\". Read-only here:\nit is set from a signed-in browser session only, never with a token."
          }
        }
      },
      "Member": {
        "type": "object",
        "description": "A delivery of a family, as an answer names it.",
        "required": [
          "id",
          "state"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId"
          },
          "state": {
            "$ref": "#/components/schemas/DeliveryState"
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "The snapshot's tag; `null` for the delivery the snapshots were made from."
          }
        }
      },
      "Mode": {
        "type": "string",
        "description": "How a delivery is kept. Stored as text in `deliveries.mode`, added by the\nmigration `*_delivery_mode.sql`; `Frozen` by `0053_snapshots.sql`.",
        "enum": [
          "one_off",
          "maintained",
          "frozen"
        ]
      },
      "ModeRequest": {
        "type": "object",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "description": "`\"one_off\"` or `\"maintained\"`: the whole mode, not a change, so\nsending it twice changes nothing."
          }
        },
        "additionalProperties": false
      },
      "NameRule": {
        "type": "string",
        "description": "Whether the contributor's page asks for a name.",
        "enum": [
          "off",
          "optional",
          "required"
        ]
      },
      "Note": {
        "type": "string",
        "description": "A file's note: trimmed, at most 2000 characters, newlines as `\\n`.\nEmpty means no note, the default, and is how a note is cleared."
      },
      "OptionsRequest": {
        "type": "object",
        "description": "What a producer sends: the options to set.",
        "required": [
          "push_rails"
        ],
        "properties": {
          "push_rails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rail"
            },
            "description": "The rails the client may use to send the files to their own server:\n`\"sftp\"`, `\"s3\"`, each at most once. An empty list turns every rail\noff."
          }
        }
      },
      "OwnerDownload": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Saves the file under its name; works for 15 minutes."
          }
        }
      },
      "OwnerDownloadLink": {
        "type": "object",
        "required": [
          "id",
          "name",
          "relative_path",
          "size",
          "content_type",
          "url"
        ],
        "properties": {
          "content_type": {
            "type": "string"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "relative_path": {
            "type": "string",
            "description": "Where the file goes in a zip: folders separated by `/`, never a\nleading `/`, and no empty, `.` or `..` part."
          },
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "url": {
            "type": "string",
            "description": "Saves the file under its name; works for 15 minutes."
          }
        }
      },
      "OwnerDownloadLinks": {
        "type": "object",
        "required": [
          "items",
          "unavailable",
          "expires_in_seconds"
        ],
        "properties": {
          "expires_in_seconds": {
            "type": "integer",
            "format": "int64",
            "description": "How long each `url` works: 900.",
            "minimum": 0
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OwnerDownloadLink"
            },
            "description": "One link per file asked for that can be had, in (relative_path, id)\norder."
          },
          "unavailable": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnavailableFile"
            },
            "description": "The files asked for that this delivery holds and that cannot be had;\n`[]` when there are none."
          }
        }
      },
      "OwnerRequest": {
        "type": "object",
        "required": [
          "state",
          "message",
          "max_total_bytes",
          "max_file_bytes",
          "max_files",
          "name_rule",
          "bytes_received",
          "files_received",
          "created_at",
          "standing",
          "room",
          "account_room_bytes",
          "accepts",
          "keep_zips",
          "accepted",
          "held",
          "notify_arrivals",
          "notify_arrivals_available",
          "contributors",
          "unpacking"
        ],
        "properties": {
          "accepted": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The same as words: `[\"photos\", \"videos\"]` or `[\"any\"]`."
          },
          "accepts": {
            "$ref": "#/components/schemas/Accepts",
            "description": "What the link takes, and whether a zip is kept as it was sent."
          },
          "account_room_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "What the account can still hold: its quota less what it uses. Every\nstart is held to it as well as to the request's own room."
          },
          "bytes_received": {
            "type": "integer",
            "format": "int64"
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closed_by": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/By"
              },
              {
                "type": "null"
              }
            ]
          },
          "closes_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "contributors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContributorSummary"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "files_received": {
            "type": "integer",
            "format": "int32"
          },
          "held": {
            "type": "integer",
            "format": "int64",
            "description": "Files of this request waiting for the owner to release them: nobody\nthe delivery was sent to sees one until then."
          },
          "keep_zips": {
            "type": "boolean"
          },
          "link": {
            "type": [
              "string",
              "null"
            ],
            "description": "The link to send; only with `requests:write`."
          },
          "max_file_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "max_files": {
            "type": "integer",
            "format": "int32"
          },
          "max_total_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "message": {
            "type": "string"
          },
          "name_rule": {
            "$ref": "#/components/schemas/NameRule"
          },
          "notify_arrivals": {
            "type": "boolean",
            "description": "Whether the owner asked to be emailed when files arrive (at most one\nemail every 3 hours, with counts and the names people gave)."
          },
          "notify_arrivals_available": {
            "type": "boolean",
            "description": "Whether this deployment can send that email. When it cannot, turning\nit on is refused (422) and the app does not offer the choice."
          },
          "room": {
            "$ref": "#/components/schemas/Room"
          },
          "standing": {
            "$ref": "#/components/schemas/Standing"
          },
          "state": {
            "$ref": "#/components/schemas/FileRequestState"
          },
          "unpacking": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JobView"
            },
            "description": "The zips strangers sent that this request unpacks, newest first (at\nmost 50): who sent each, its state, how many files it added, what was\nleft out and why, in sentences. A stranger's zip is no file of the\ndelivery, so it is listed here and nowhere else."
          }
        }
      },
      "OwnerSnapshot": {
        "type": "object",
        "description": "What the producer's detail says of a delivery that is frozen.",
        "required": [
          "frozen_at",
          "manifest_sha256"
        ],
        "properties": {
          "frozen_at": {
            "type": "string",
            "format": "date-time"
          },
          "manifest_sha256": {
            "type": "string",
            "description": "The SHA-256 of the SHA256SUMS list: what to compare a copy with."
          },
          "snapshot_of": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SourceRef",
                "description": "The maintained delivery it was made from; `null` for a delivery frozen\nin place."
              },
              {
                "type": "null"
              }
            ]
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "`null` once the delivery was erased: the tag goes with it, and stays\nreserved."
          }
        }
      },
      "PartInfo": {
        "type": "object",
        "required": [
          "PartNumber",
          "Size",
          "ETag"
        ],
        "properties": {
          "ETag": {
            "type": "string"
          },
          "PartNumber": {
            "type": "integer",
            "format": "int32"
          },
          "Size": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "Presentation": {
        "type": "string",
        "description": "How a delivery is drawn. Stored as text in `deliveries.presentation`.",
        "enum": [
          "pictures",
          "files"
        ]
      },
      "Preview": {
        "type": "object",
        "required": [
          "files",
          "frees_bytes",
          "kept",
          "account_used_bytes",
          "account_quota_bytes"
        ],
        "properties": {
          "account_quota_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "account_used_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "What your account uses now, and its limit, in bytes."
          },
          "files": {
            "type": "integer",
            "description": "How many of the named files a prune would prune (the ones already\npruned are not counted).",
            "minimum": 0
          },
          "frees_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "What it frees in your storage figure NOW, in bytes. The files are\ndeleted from storage about a week later."
          },
          "kept": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Kept"
            },
            "description": "Files another of your active deliveries also holds: they stay stored,\nand counted, there."
          }
        }
      },
      "PreviewAnswer": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PreviewPicture"
          },
          {
            "$ref": "#/components/schemas/PreviewVideo"
          },
          {
            "$ref": "#/components/schemas/PreviewPoster"
          }
        ],
        "description": "What a 200 says: a picture, a video's playable copy, or a video's poster\nwith what is known of its copy. Untagged, so each is written as its own\nobject: a picture's answer has no `kind`.\n\nIn the OpenAPI document this is a `oneOf`, and an answer must match\nexactly one branch, so the three are told apart there as on the wire: a\nvideo and a poster by the one word their `kind` can be, and a picture by\nhaving nothing but its two fields (its schema is closed, which is also a\npromise that the picture's answer stays exactly as it has been since\nbefore videos; tests/owner_previews/ checks each real answer against the\ndocument)."
      },
      "PreviewPicture": {
        "type": "object",
        "description": "The preview picture is made.",
        "required": [
          "url",
          "expires_in_seconds"
        ],
        "properties": {
          "expires_in_seconds": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "url": {
            "type": "string",
            "description": "The picture, inline as `image/jpeg`; works for 15 minutes."
          }
        },
        "additionalProperties": false
      },
      "PreviewPoster": {
        "type": "object",
        "description": "A video's poster, with what is known of its copy: an ordinary picture\nanswer (`kind`: `image`) for a page that knows nothing of videos.",
        "required": [
          "kind",
          "url",
          "expires_in_seconds",
          "video"
        ],
        "properties": {
          "expires_in_seconds": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "kind": {
            "type": "string",
            "description": "The `kind` of a poster's answer: a picture, to a page that knows nothing\nof videos.",
            "enum": [
              "image"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the copy will not be made, as a fixed word: `too_long`,\n`too_large`, `limit_exceeded`, `decode_failed`, `unsupported`."
          },
          "url": {
            "type": "string",
            "description": "The poster, inline as `image/jpeg`."
          },
          "video": {
            "type": "string",
            "description": "`preparing` (ask again) or `unavailable` (for good)."
          }
        }
      },
      "PreviewPreparing": {
        "type": "object",
        "description": "What a 202 says: the preview will be made; ask again.",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string",
            "description": "`preparing`."
          }
        }
      },
      "PreviewVideo": {
        "type": "object",
        "description": "A video's playable copy is ready: the answer a page that knows videos\nplays. \"kind\" is the word it looks for.",
        "required": [
          "kind",
          "url",
          "expires_in_seconds"
        ],
        "properties": {
          "capped_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Only when the copy covers just the first part of the video: 300.",
            "minimum": 0
          },
          "expires_in_seconds": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "kind": {
            "type": "string",
            "description": "The `kind` of a video's answer: the one word it can be.",
            "enum": [
              "video"
            ]
          },
          "poster_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "description": "The playable copy, inline as `video/mp4`; it answers `Range` requests."
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "The problem details body, as the OpenAPI document describes it.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string",
            "description": "What went wrong and what to do next."
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "A stable URL for this kind of failure; branch on this, not on\n`title` or `detail`. Two 409s are told apart by it: `conflict` (what\nwas asked is already so, or someone else got there first: this\ncontent is already stored, attach it instead) and\n`delivery-not-writable` (the delivery is deleted, being erased or\nerased, so nothing can be added to or changed in it; restore it\nfirst if it is only deleted). Two more 409s are about content\nTheirway removed after a report: `removed-by-theirway` (that delivery\ncannot be restored or changed) and `file-removed-by-theirway` (the\nfile went down with it and cannot be attached or uploaded again).\nA client's test of a destination that ran out its 30 minutes answers\n`test-expired` (409): test the destination again. A client's request\nthat met another one being handled for the same link answers\n`link-busy` (409): nothing was done, ask again in a moment.\nA client's link answers 410 in two ways, told apart by this type:\n`delivery-deleted` (the whole delivery is gone) and, for one file of a\ndelivery that is still there, `file-retracted` (the sender took it\nback, with a `reason`) or `file-removed` (pruned by the sender, or\ntaken down by Theirway; `removed_by`).\nA file request's link (`/api/req`) answers its contributors with\nproblems of their own: `request-full` (409: no room for this file),\n`file-too-large` (413), `request-closed` (409), `request-removed`\n(410: the owner removed the request, or Theirway took it down),\n`request-unavailable` (410: the owner cannot receive files right\nnow; no reason is given), `wrong-kind` (422: only photos and videos) and `too-many-requests`\n(429, with `Retry-After`). A bad or stopped link is the bare 404.\nA snapshot that cannot be made answers `snapshot-refused` (409): which\nof the chosen files cannot go in it, each with its `why`, in the `files`\nmember. A frozen delivery refuses changes with `delivery-not-writable`.\nEmailing a link has its own answers: `limit-reached` (429; for the\nsame link emailed again too soon it also carries a `retry_after`\nmember, RFC 3339 UTC) and `unavailable` (503: the email was not, or\nmay not have been, handed to the mail service; `detail` says which).\nLettermint's own webhook calls (`POST /api/mail/lettermint`, not part\nof the producer API) are answered `signature-refused` (401) when they\nare not signed with this server's webhook secret."
          }
        }
      },
      "ProducerId": {
        "type": "string",
        "format": "uuid"
      },
      "PruneRequest": {
        "type": "object",
        "required": [
          "file_ids"
        ],
        "properties": {
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to prune, 1 to 200, all of this delivery. A file that is\nalready pruned is counted `unchanged`."
          }
        },
        "additionalProperties": false
      },
      "Pruned": {
        "type": "object",
        "required": [
          "pruned",
          "unchanged",
          "frees_bytes"
        ],
        "properties": {
          "frees_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "What this call freed in your storage figure, in bytes."
          },
          "pruned": {
            "type": "integer",
            "description": "Files pruned by this call.",
            "minimum": 0
          },
          "unchanged": {
            "type": "integer",
            "description": "Files that were pruned already.",
            "minimum": 0
          }
        }
      },
      "PushRails": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Rail"
        },
        "description": "The rails that are on for one delivery: only known rails, each once,\nalways in `Rail::ALL` order. Empty means all off, the default."
      },
      "Rail": {
        "type": "string",
        "description": "A way to send files to the client's own server. Declaration order is\nthe order rails are listed and reported in.",
        "enum": [
          "sftp",
          "s3"
        ]
      },
      "RecipientId": {
        "type": "string",
        "format": "uuid"
      },
      "RecipientItem": {
        "type": "object",
        "required": [
          "id",
          "revoked"
        ],
        "properties": {
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_avatar": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this person has a picture, as far as is known without asking\nGravatar: `true`, `false` (also when they have no address), or `null`\n(not looked up yet: ask `.../avatar`). See `GET /me`."
          },
          "id": {
            "$ref": "#/components/schemas/RecipientId"
          },
          "link": {
            "type": [
              "string",
              "null"
            ],
            "description": "The recipient's link; only with the `recipients:send` scope."
          },
          "link_email": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/LinkEmailItem",
                "description": "How the link's latest email stands (`POST .../email`), or `null` when\nit was never emailed. \"Sent\" means handed over to the mail service,\nwhich is not \"delivered\": its `arrival` (`arrived` or `bounced`) comes\nfrom the mail service's own report, and only once Theirway is set up to\nreceive it. `reply_forwarded_at` is when a client's reply to it was\nlast passed on to the producer. Named apart from `email`, the address."
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "revoked": {
            "type": "boolean"
          }
        }
      },
      "ReinstateRequest": {
        "type": "object",
        "required": [
          "file_ids"
        ],
        "properties": {
          "everywhere": {
            "type": "boolean",
            "description": "Reinstate the same bytes in every delivery of the family where they\nwere retracted for the SAME reason as here. A reference retracted for\nanother reason stays retracted and is named in `left`. Leave out to\nreinstate here only."
          },
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to reinstate, 1 to 500, all of this delivery."
          }
        },
        "additionalProperties": false
      },
      "Reinstated": {
        "type": "object",
        "required": [
          "reinstated",
          "unchanged",
          "in",
          "left"
        ],
        "properties": {
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            },
            "description": "The deliveries the call reached."
          },
          "left": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Left"
            },
            "description": "Reinstating everywhere: the references to the same bytes that stay\nretracted, because they were retracted for another reason, each with\nthat reason. Empty otherwise."
          },
          "reinstated": {
            "type": "integer",
            "description": "References that were retracted and are available again.",
            "minimum": 0
          },
          "unchanged": {
            "type": "integer",
            "description": "References that were available already.",
            "minimum": 0
          }
        }
      },
      "RelativePath": {
        "type": "string",
        "description": "'/'-separated folders and a file name: no empty, \".\" or \"..\" part, no\nleading '/' or drive letter, no backslash, no control or direction\ncharacters. A value of this type is always clean; nothing behind the\nedge checks it again."
      },
      "ReleaseRequest": {
        "type": "object",
        "required": [
          "file_ids"
        ],
        "properties": {
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to release, 1 to 500, all of this delivery."
          }
        },
        "additionalProperties": false
      },
      "Released": {
        "type": "object",
        "required": [
          "released",
          "unchanged"
        ],
        "properties": {
          "released": {
            "type": "integer",
            "description": "Files that were waiting and can now be had by the people you sent the\ndelivery to.",
            "minimum": 0
          },
          "unchanged": {
            "type": "integer",
            "description": "Files that were not waiting (released already), left as they were.",
            "minimum": 0
          }
        }
      },
      "RemovedFile": {
        "type": "object",
        "description": "One file that was pruned from the delivery, as its owner reads it. The\nname is the producer's own text: draw it as text, never as markup.",
        "required": [
          "id",
          "name",
          "relative_path",
          "size",
          "removed_at",
          "removed_by"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The id the file had in `files`; a trail row names it too."
          },
          "name": {
            "type": "string"
          },
          "relative_path": {
            "type": "string"
          },
          "removed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was pruned (UTC)."
          },
          "removed_by": {
            "type": "string",
            "description": "Who pruned it: `producer`, the owner, by a session or by a token."
          },
          "sha256": {
            "type": [
              "string",
              "null"
            ],
            "description": "The SHA-256 the client is shown for it; `null` when it had none (a\nfile added through a request link, an upload that sent none, or one\nolder than content hashes)."
          },
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "via_token": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AccessTokenId",
                "description": "The access token that made the call; `null` for a session."
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Reported": {
        "type": "object",
        "description": "What the client's page last reported it downloaded: the page's word.",
        "required": [
          "at"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64"
          },
          "count": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "How many files, when the report said."
          },
          "method": {
            "type": [
              "string",
              "null"
            ],
            "description": "`zip` or `files`."
          }
        }
      },
      "RequestSettings": {
        "type": "object",
        "description": "The body of `POST` and `PATCH .../request`. Every field is optional.",
        "properties": {
          "accepts": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Accepts",
                "description": "What the link takes: `photos_and_videos` (the default) or `any`. A\nfile nothing has checked (every file on an `any` request, a kept zip)\nwaits for the owner's release before anyone the delivery was sent to\nsees it."
              },
              {
                "type": "null"
              }
            ]
          },
          "closes_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the link stops taking files: in the future, at most 90 days away."
          },
          "keep_zips": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Keep a zip file as it was sent instead of unpacking it. Always true\nwhen `accepts` is `any`; sending `false` with it is refused."
          },
          "max_file_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Bytes in one file; a stranger's file over it is refused (413)."
          },
          "max_files": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Files in all, 1 to 10,000."
          },
          "max_total_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Bytes in all the link will take, at most the account's quota."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the contributor's page says; up to 2000 characters."
          },
          "name_rule": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/NameRule",
                "description": "Whether the page asks for a name: `off`, `optional` or `required`."
              },
              {
                "type": "null"
              }
            ]
          },
          "notify_arrivals": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Email the owner when files arrive (at most one email every 3 hours per\nrequest, with counts and the names people gave). `true` turns it on\nfrom now, `false` off; left out, it stays as it is. Off for a new\nrequest."
          }
        },
        "additionalProperties": false
      },
      "RetractRequest": {
        "type": "object",
        "required": [
          "file_ids",
          "reason"
        ],
        "properties": {
          "everywhere": {
            "type": "boolean",
            "description": "Retract the same bytes in every snapshot of the delivery they were made\nfrom, and in that delivery, too (a deleted snapshot included, so a\nrestore does not bring the file back). Leave out to retract here only."
          },
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The files to retract, 1 to 500, all of this delivery."
          },
          "reason": {
            "type": "string",
            "description": "What the client reads in place of the file: 1 to 500 characters of\nplain text. Drawn as text, never as markup."
          }
        },
        "additionalProperties": false
      },
      "Retracted": {
        "type": "object",
        "required": [
          "retracted",
          "unchanged",
          "in",
          "still_in"
        ],
        "properties": {
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            },
            "description": "The deliveries the call reached: this one, or with `everywhere` every\ndelivery of the family that holds the bytes."
          },
          "retracted": {
            "type": "integer",
            "description": "References that were available and are retracted now.",
            "minimum": 0
          },
          "still_in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            },
            "description": "Retracting here only: the other deliveries of the family where the same\nbytes are still available (a snapshot, or the delivery it was made\nfrom). Empty with `everywhere`."
          },
          "unchanged": {
            "type": "integer",
            "description": "References that were retracted already, and were left as they were\n(with their first reason).",
            "minimum": 0
          }
        }
      },
      "Role": {
        "type": "string",
        "description": "Backed by `text` in Postgres (the check constraint in migration 0016).",
        "enum": [
          "producer",
          "superuser"
        ]
      },
      "Room": {
        "type": "object",
        "description": "What is left to give: bytes and files, never negative.",
        "required": [
          "bytes",
          "files"
        ],
        "properties": {
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "files": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "SendAnswer": {
        "type": "object",
        "description": "What the producer is told when Lettermint took the email. No link and no\naddress: the answer is not a place to leak either.",
        "required": [
          "send_id",
          "state",
          "sent_at"
        ],
        "properties": {
          "send_id": {
            "$ref": "#/components/schemas/MailSendId"
          },
          "sent_at": {
            "type": "string",
            "format": "date-time"
          },
          "state": {
            "$ref": "#/components/schemas/LinkEmailState",
            "description": "Always `\"sent\"`: handed over to Lettermint, which is not \"delivered\"."
          }
        }
      },
      "Sha256Hex": {
        "type": "string",
        "description": "A SHA-256 as 64 lowercase hex characters. Checked once, when the request\nis read: a value of this type is always well-formed, so nothing behind\nthe edge checks it again."
      },
      "ShownArrival": {
        "type": "string",
        "description": "What an owner may be told of an arrival: two words, never a complaint or a\nprovider suppression by name (the not-an-oracle rule: a complaint is the\nperson's wish, like a stop, and a suppression could be somebody else's\nbounce). The stored value keeps the truth for the operator.",
        "enum": [
          "arrived",
          "bounced"
        ]
      },
      "SignPartResponse": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "PUT the part's bytes here, straight to storage, within an hour, and\nkeep the `ETag` header of the answer for completing."
          }
        }
      },
      "SnapshotItem": {
        "type": "object",
        "required": [
          "id",
          "frozen_at",
          "files",
          "bytes",
          "manifest_sha256",
          "state",
          "links"
        ],
        "properties": {
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "files": {
            "type": "integer",
            "format": "int32",
            "description": "How many files and bytes the list fixed."
          },
          "frozen_at": {
            "type": "string",
            "format": "date-time"
          },
          "id": {
            "$ref": "#/components/schemas/DeliveryId",
            "description": "The snapshot's own delivery id."
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkItem"
            },
            "description": "Who had it: each of its recipient links and what its holder did, from\nthe events that exist. `[]` for a snapshot nobody was given a link to,\nand for one being erased or erased, whose links answer 410 for good."
          },
          "manifest_sha256": {
            "type": "string",
            "description": "The SHA-256 of the SHA256SUMS list."
          },
          "state": {
            "$ref": "#/components/schemas/DeliveryState",
            "description": "The snapshot's own lifecycle: `active`, `deleted`, `erasing` or\n`erased`."
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "`null` once the snapshot was erased."
          }
        }
      },
      "SnapshotList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SnapshotItem"
            },
            "description": "Newest first, at most 200."
          }
        }
      },
      "SnapshotMade": {
        "type": "object",
        "required": [
          "id",
          "snapshot_of",
          "tag",
          "frozen_at",
          "files",
          "bytes",
          "manifest_sha256"
        ],
        "properties": {
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "files": {
            "type": "integer",
            "format": "int32"
          },
          "frozen_at": {
            "type": "string",
            "format": "date-time"
          },
          "id": {
            "$ref": "#/components/schemas/DeliveryId",
            "description": "The snapshot's own delivery id: give it recipient links."
          },
          "manifest_sha256": {
            "type": "string",
            "description": "The SHA-256 of the SHA256SUMS list (`sha256sum SHA256SUMS`): mail it\nfrom your own mail program, so a copy exists outside our database."
          },
          "snapshot_of": {
            "$ref": "#/components/schemas/DeliveryId",
            "description": "The maintained delivery it was made from."
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "SourceRef": {
        "type": "object",
        "description": "The delivery a snapshot was made from.",
        "required": [
          "id",
          "title"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId"
          },
          "title": {
            "type": "string",
            "description": "Its title now; `\"Deleted delivery\"` once it was erased."
          }
        }
      },
      "Standing": {
        "type": "string",
        "description": "Whether a request accepts, and if not, why.",
        "enum": [
          "removed",
          "taken_down",
          "closed",
          "full",
          "accepting"
        ]
      },
      "StoredFileId": {
        "type": "string",
        "format": "uuid"
      },
      "Tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "A file's tags: each valid, none repeated (in any case), at most 20, in\nthe order the producer gave them. Empty means none, the default."
      },
      "ThumbnailUpload": {
        "type": "object",
        "required": [
          "content_type"
        ],
        "properties": {
          "content_type": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "PUT the picture here within 15 minutes, with `content_type` as the\n`Content-Type` header; `null` when the file already has a thumbnail."
          }
        }
      },
      "TrailItem": {
        "type": "object",
        "description": "One change, as the owner reads it. `file_id`, `size`, `sha256` and\n`reason` are `null` where they do not apply (a mode change has no file; a\nremoval has no fingerprint), and `reason` is `null` once the delivery was\nerased. Never a file's name.",
        "required": [
          "action",
          "at",
          "by"
        ],
        "properties": {
          "action": {
            "type": "string",
            "description": "`maintain`, `settle`, `freeze`, `retract`, `reinstate`, `prune` or\n`remove`."
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "by": {
            "type": "string",
            "description": "`producer`, or `contributor` for a file a stranger took away."
          },
          "file_count": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "file_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "files": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "How many files this line is about: more than one only for the owner's\nremovals of one moment, folded into one line (a removal of everything\none contributor added). `null` for a change of mode."
          },
          "from": {
            "type": [
              "string",
              "null"
            ],
            "description": "The mode or file state before."
          },
          "manifest_sha256": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only for `freeze`: the SHA-256 of the list that was fixed, and how many\nfiles and bytes it holds."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256": {
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64"
          },
          "snapshot": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TrailSnapshot",
                "description": "Only for `freeze`: the frozen delivery. In the trail of the delivery a\nsnapshot was made from, the snapshot's freeze reads here too."
              },
              {
                "type": "null"
              }
            ]
          },
          "to": {
            "type": [
              "string",
              "null"
            ],
            "description": "The mode or file state after; `null` for a removal."
          },
          "total_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64"
          },
          "via_token": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AccessTokenId",
                "description": "The access token that made the call; `null` for a session."
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "TrailPage": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrailItem"
            },
            "description": "Newest first."
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `after` for the next page; `null` on the last one."
          }
        }
      },
      "TrailSnapshot": {
        "type": "object",
        "description": "The delivery a `freeze` row is about.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId",
            "description": "The frozen delivery: the one whose trail this is, or one of its\nsnapshots."
          },
          "snapshot_of": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DeliveryId",
                "description": "The maintained delivery it was made from; `null` for a delivery frozen\nin place."
              },
              {
                "type": "null"
              }
            ]
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its tag, read from the delivery now: `null` once it was erased (the tag\nis blanked there, and stays reserved)."
          }
        }
      },
      "UnavailableFile": {
        "type": "object",
        "required": [
          "id",
          "state"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "$ref": "#/components/schemas/UnavailableFileState"
          }
        }
      },
      "UnavailableFileState": {
        "type": "string",
        "description": "Why a file of the delivery cannot be had by its owner.",
        "enum": [
          "removed_by_theirway"
        ]
      },
      "UnpackJobId": {
        "type": "string",
        "format": "uuid"
      },
      "Unpacking": {
        "type": "object",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string",
            "description": "`queued`: the unpacker takes it in turn."
          }
        }
      },
      "UploadId": {
        "type": "string",
        "description": "The S3 multipart upload id (`uploads.s3_upload_id`), not the row's own\nprimary key -- it's what every upload-scoped route actually addresses\n(see uploads/rules.rs). A `String`, not a `Uuid`: S3 mints it, Theirway\nonly stores and echoes it back."
      }
    },
    "securitySchemes": {
      "access_token": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tw_pat_...",
        "description": "A personal access token. Each operation lists the scope it needs; a token without it gets a 403 missing-scope problem."
      },
      "session_cookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "tw_session",
        "description": "The web app's session; holds every producer scope."
      }
    }
  }
}