{ "components": { "schemas": { "AcceptedResponse": { "additionalProperties": true, "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "type": "object" }, "AccountProblem": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "format": "int64", "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "code", "title", "status", "type", "detail" ], "type": "object" }, "AccountSession": { "additionalProperties": true, "properties": { "auth_method": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "last_seen_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "created_at", "last_seen_at", "auth_method", "current" ], "type": "object" }, "AccountState": { "additionalProperties": true, "properties": { "active_library_id": { "type": "string" }, "auth_enabled": { "type": "boolean" }, "csrf_token": { "type": "string" }, "libraries": { "items": { "$ref": "#/components/schemas/Library" }, "type": [ "array", "null" ] }, "passkeys_available": { "type": "boolean" }, "recovery_authenticated": { "type": "boolean" }, "user": { "additionalProperties": true, "properties": { "display_name": { "type": "string" }, "id": { "type": "string" }, "instance_admin": { "type": "boolean" } }, "required": [ "id", "display_name", "instance_admin" ], "type": [ "object", "null" ] } }, "required": [ "passkeys_available", "recovery_authenticated", "auth_enabled", "user", "csrf_token", "libraries", "active_library_id" ], "type": "object" }, "AccountUser": { "additionalProperties": true, "properties": { "display_name": { "type": "string" }, "id": { "type": "string" }, "instance_admin": { "type": "boolean" } }, "required": [ "id", "display_name", "instance_admin" ], "type": "object" }, "Addition": { "additionalProperties": false, "properties": { "buy": { "maxLength": 200, "type": "string" }, "category": { "maxLength": 100, "type": "string" }, "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "note": { "maxLength": 2000, "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "AllergenDeclaration": { "additionalProperties": false, "properties": { "condition": { "maxLength": 1000000, "type": "string" }, "presence": { "description": "contains: present; may_contain: precautionary or cross-contact warning; free_from: explicit absence claim", "enum": [ "contains", "may_contain", "free_from" ], "type": "string" }, "substance": { "description": "The substance as the source names it", "maxLength": 1000, "minLength": 1, "type": "string" }, "text": { "description": "The complete authored statement", "maxLength": 1000000, "minLength": 1, "type": "string" }, "variant_ref": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": [ "text", "substance", "presence" ], "type": "object" }, "AlternativeOption": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "kind": { "enum": [ "simple", "sum" ], "type": "string" }, "terms": { "items": { "$ref": "#/components/schemas/SimpleQuantity" }, "maxItems": 100, "type": [ "array", "null" ] }, "unit": { "maxLength": 255, "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "Amount": { "additionalProperties": false, "properties": { "approximate": { "type": "boolean" }, "max": { "maxLength": 128, "pattern": "^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "min": { "maxLength": 128, "pattern": "^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "value": { "maxLength": 128, "pattern": "^(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" } }, "type": "object" }, "Apply-bulk-book-recipesRequest": { "additionalProperties": false, "properties": { "add_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "book_id": { "type": "string" }, "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "member": { "type": "boolean" }, "remove_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Apply-bulk-read-recipesRequest": { "additionalProperties": false, "properties": { "add_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "book_id": { "type": "string" }, "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "member": { "type": "boolean" }, "remove_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Apply-bulk-restore-recipesRequest": { "additionalProperties": false, "properties": { "add_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "book_id": { "type": "string" }, "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "member": { "type": "boolean" }, "remove_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Apply-bulk-tags-recipesRequest": { "additionalProperties": false, "properties": { "add_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "book_id": { "type": "string" }, "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "member": { "type": "boolean" }, "remove_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Apply-bulk-trash-recipesRequest": { "additionalProperties": false, "properties": { "add_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "book_id": { "type": "string" }, "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "member": { "type": "boolean" }, "remove_tags": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Asset": { "additionalProperties": false, "properties": { "alt": { "maxLength": 1000, "type": "string" }, "caption": { "maxLength": 1000000, "type": "string" }, "creator": { "description": "Who the source credits with creating the file", "maxLength": 1000, "type": "string" }, "credit": { "description": "Authored credit line", "maxLength": 1000000, "type": "string" }, "id": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "license": { "$ref": "#/components/schemas/AssetLicense", "description": "License the source applies to the file; absent means unknown" }, "media_type": { "maxLength": 255, "pattern": "^[A-Za-z0-9!#$\u0026^_.+-]+/[A-Za-z0-9!#$\u0026^_.+-]+$", "type": "string" }, "path": { "maxLength": 512, "pattern": "^assets/[A-Za-z0-9][A-Za-z0-9._/-]{0,510}$", "type": "string" }, "rights": { "description": "Authored copyright or rights statement", "maxLength": 1000000, "type": "string" }, "role": { "enum": [ "image", "source", "other" ], "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "size": { "format": "int64", "minimum": 0, "type": "integer" }, "source_url": { "description": "Page or file the asset came from", "format": "uri", "maxLength": 10000, "type": "string" } }, "required": [ "id", "path", "media_type", "sha256", "size" ], "type": "object" }, "AssetBlob": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" }, "media_type": { "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "size": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "id", "sha256", "media_type", "size", "created_at" ], "type": "object" }, "AssetLicense": { "additionalProperties": false, "properties": { "name": { "maxLength": 1000, "type": "string" }, "url": { "format": "uri", "maxLength": 10000, "type": "string" } }, "type": "object" }, "AssetReference": { "additionalProperties": true, "properties": { "alt": { "type": "string" }, "asset_id": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" }, "caption": { "type": "string" }, "local_asset_id": { "type": "string" }, "media_type": { "type": "string" }, "url": { "description": "Immutable asset URL", "type": "string" } }, "required": [ "asset_id", "local_asset_id", "media_type" ], "type": "object" }, "Attempt": { "additionalProperties": true, "properties": { "at": { "format": "date-time", "type": "string" }, "code": { "type": "string" }, "duration_ms": { "format": "int64", "type": "integer" }, "excerpt": { "type": "string" }, "id": { "type": "string" }, "status": { "format": "int64", "type": "integer" } }, "required": [ "id", "at", "code", "duration_ms" ], "type": "object" }, "AuditEvent": { "additionalProperties": true, "properties": { "action": { "type": "string" }, "actor_id": { "type": "string" }, "correlation_id": { "type": "string" }, "created_at": { "format": "int64", "type": "integer" }, "credential_id": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "library_id": { "type": "string" }, "outcome": { "type": "string" }, "target_id": { "type": "string" }, "target_type": { "type": "string" } }, "required": [ "id", "created_at", "actor_id", "credential_id", "action", "target_type", "target_id", "library_id", "correlation_id", "outcome" ], "type": "object" }, "AuditResponse": { "additionalProperties": true, "properties": { "events": { "items": { "$ref": "#/components/schemas/AuditEvent" }, "type": [ "array", "null" ] } }, "required": [ "events" ], "type": "object" }, "Author": { "additionalProperties": false, "properties": { "kind": { "description": "Absent when the source does not support a defensible classification", "enum": [ "person", "organization", "other" ], "type": "string" }, "kind_label": { "description": "Source-authored classification used only with kind other", "maxLength": 1000, "type": "string" }, "name": { "maxLength": 1000, "minLength": 1, "type": "string" }, "url": { "format": "uri", "maxLength": 10000, "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:", "type": "string" } }, "required": [ "name" ], "type": "object" }, "Book": { "additionalProperties": true, "properties": { "author": { "type": "string" }, "cover_asset_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "edition": { "type": "string" }, "editor": { "type": "string" }, "entries": { "items": { "$ref": "#/components/schemas/BookEntry" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "isbn": { "type": "string" }, "kind": { "enum": [ "personal", "publication" ], "type": "string" }, "publication_date": { "type": "string" }, "publisher": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "sections": { "items": { "$ref": "#/components/schemas/BookSection" }, "type": [ "array", "null" ] }, "subtitle": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "title", "sections", "entries", "revision", "created_at", "updated_at" ], "type": "object" }, "BookEntry": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "library_entry_id": { "description": "Identifier of the member entry in the local Savorum library", "type": "string" }, "note": { "type": "string" }, "position": { "format": "int64", "type": "integer" }, "recipe_state": { "enum": [ "active", "trash" ], "type": "string" }, "section_id": { "type": "string" } }, "required": [ "library_entry_id", "position", "recipe_state" ], "type": "object" }, "BookEntryInput": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "library_entry_id": { "description": "Identifier of the member entry in the local Savorum library", "type": "string" }, "note": { "type": "string" }, "position": { "format": "int64", "type": "integer" }, "section_id": { "type": "string" } }, "required": [ "library_entry_id", "position" ], "type": "object" }, "BookInput": { "additionalProperties": false, "properties": { "author": { "type": "string" }, "cover_asset_id": { "type": "string" }, "description": { "type": "string" }, "edition": { "type": "string" }, "editor": { "type": "string" }, "entries": { "items": { "$ref": "#/components/schemas/BookEntryInput" }, "maxItems": 1000, "type": [ "array", "null" ] }, "isbn": { "type": "string" }, "kind": { "enum": [ "personal", "publication" ], "type": "string" }, "publication_date": { "type": "string" }, "publisher": { "type": "string" }, "sections": { "items": { "$ref": "#/components/schemas/BookSection" }, "maxItems": 100, "type": [ "array", "null" ] }, "subtitle": { "type": "string" }, "title": { "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "kind", "title", "sections", "entries" ], "type": "object" }, "BookMembershipInput": { "additionalProperties": false, "properties": { "book_id": { "minLength": 1, "type": "string" }, "member": { "description": "True to place the recipe in the book, false to take it out", "type": "boolean" }, "revision": { "description": "Book revision this change expects", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "book_id", "revision", "member" ], "type": "object" }, "BookRevision": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "book": { "$ref": "#/components/schemas/Book" }, "cause": { "enum": [ "api", "manual_edit", "restore", "trash", "recipe_lifecycle" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "source_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "state": { "enum": [ "active", "trash" ], "type": "string" } }, "required": [ "book", "state", "cause", "created_at" ], "type": "object" }, "BookRevisionSummary": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "book_id": { "type": "string" }, "cause": { "enum": [ "api", "manual_edit", "restore", "trash", "recipe_lifecycle" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "source_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "state": { "enum": [ "active", "trash" ], "type": "string" } }, "required": [ "book_id", "revision", "state", "cause", "created_at" ], "type": "object" }, "BookRevisionsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BookRevisionSummary" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "BookSection": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "position": { "format": "int64", "type": "integer" }, "title": { "type": "string" } }, "required": [ "title", "position" ], "type": "object" }, "BookSelectionSummary": { "additionalProperties": true, "properties": { "author": { "type": "string" }, "cover_asset_id": { "type": "string" }, "edition": { "type": "string" }, "editor": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "subtitle": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "revision", "kind", "title" ], "type": "object" }, "BookSourceRecipe": { "additionalProperties": true, "properties": { "library_entry_id": { "description": "Identifier of the sourced entry in the local Savorum library", "type": "string" }, "original_title": { "type": "string" }, "page_end": { "format": "int64", "minimum": 0, "type": "integer" }, "page_start": { "format": "int64", "minimum": 0, "type": "integer" }, "title": { "type": "string" } }, "required": [ "library_entry_id", "title" ], "type": "object" }, "BookSourceRecipesOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BookSourceRecipe" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "BookSummary": { "additionalProperties": true, "properties": { "author": { "type": "string" }, "contains_entry": { "type": "boolean" }, "cover_asset_id": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "entry_count": { "format": "int64", "minimum": 0, "type": "integer" }, "id": { "type": "string" }, "kind": { "enum": [ "personal", "publication" ], "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "title", "entry_count", "revision", "updated_at" ], "type": "object" }, "BooksOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BookSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "BulkItemResult": { "additionalProperties": true, "properties": { "book_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "code": { "type": "string" }, "current_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "id": { "type": "string" }, "import": { "$ref": "#/components/schemas/ImportJobItemResource" }, "recipe": { "$ref": "#/components/schemas/LibraryEntry" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "status": { "enum": [ "succeeded", "failed", "pending", "running", "skipped", "cancelled" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "BulkOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BulkItemResult" }, "type": [ "array", "null" ] }, "job": { "$ref": "#/components/schemas/JobResource" }, "policy": { "enum": [ "partial-success" ], "type": "string" } }, "required": [ "policy" ], "type": "object" }, "CalendarFeed": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "created_by_name": { "type": "string" }, "id": { "type": "string" }, "last_read_at": { "format": "date-time", "type": "string" }, "mine": { "type": "boolean" }, "name": { "type": "string" }, "rotated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "created_at", "created_by", "created_by_name", "mine" ], "type": "object" }, "CalendarFeedInputBody": { "additionalProperties": false, "properties": { "name": { "description": "What the feed is called in calendar applications", "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CalendarFeedSecret": { "additionalProperties": true, "properties": { "feed": { "$ref": "#/components/schemas/CalendarFeed" }, "path": { "type": "string" }, "url": { "type": "string" } }, "required": [ "feed", "path" ], "type": "object" }, "CalendarFeedsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/CalendarFeed" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Capabilities": { "additionalProperties": true, "properties": { "api_major": { "format": "int64", "type": "integer" }, "auth_enabled": { "type": "boolean" }, "auth_features": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "auth_methods": { "items": { "$ref": "#/components/schemas/CapabilityAuthMethod" }, "type": [ "array", "null" ] }, "event_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "exporters": { "items": { "$ref": "#/components/schemas/CapabilityAdapter" }, "type": [ "array", "null" ] }, "features": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "importers": { "items": { "$ref": "#/components/schemas/CapabilityAdapter" }, "type": [ "array", "null" ] }, "limits": { "$ref": "#/components/schemas/CapabilityLimits" }, "product": { "type": "string" }, "schema_version": { "format": "int64", "type": "integer" }, "sref_read": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "sref_write": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "version": { "type": "string" } }, "required": [ "schema_version", "product", "version", "api_major", "auth_enabled", "auth_methods" ], "type": "object" }, "CapabilityAdapter": { "additionalProperties": true, "properties": { "collection": { "type": "boolean" }, "extensions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "input_kinds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "media_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "name", "collection" ], "type": "object" }, "CapabilityAuthMethod": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "kind" ], "type": "object" }, "CapabilityLimits": { "additionalProperties": true, "properties": { "artifact_hours": { "format": "int64", "type": "integer" }, "async_items": { "format": "int64", "type": "integer" }, "bulk_items": { "format": "int64", "type": "integer" }, "export_artifact_bytes": { "format": "int64", "type": "integer" }, "export_recipes": { "format": "int64", "type": "integer" }, "grocery_addition_items": { "format": "int64", "type": "integer" }, "import_file_bytes": { "format": "int64", "type": "integer" }, "lookup_items": { "format": "int64", "type": "integer" }, "pantry_entries": { "format": "int64", "type": "integer" }, "print_recipes": { "description": "Most recipes one printed document holds, when printing is available", "format": "int64", "type": "integer" }, "request_body_bytes": { "format": "int64", "type": "integer" }, "retry_receipt_hours": { "format": "int64", "type": "integer" }, "suggestion_items": { "format": "int64", "type": "integer" } }, "required": [ "suggestion_items", "lookup_items", "grocery_addition_items", "retry_receipt_hours", "bulk_items", "export_recipes", "pantry_entries", "async_items", "import_file_bytes", "request_body_bytes", "export_artifact_bytes", "artifact_hours" ], "type": "object" }, "ChangedEntriesOutputBody": { "additionalProperties": true, "properties": { "items": { "description": "The recipes that received a new revision", "items": { "$ref": "#/components/schemas/LibraryEntry" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Commit-automation-importRequest": { "additionalProperties": false, "properties": { "policy": { "enum": [ "require-no-warnings", "allow-warnings" ], "type": "string" } }, "required": [ "policy" ], "type": "object" }, "CookingHistory": { "additionalProperties": true, "properties": { "imported_baselines": { "items": { "$ref": "#/components/schemas/ImportedCookCountBaseline" }, "type": [ "array", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/CookingRecord" }, "type": [ "array", "null" ] }, "last_cooked": { "format": "date", "type": "string" }, "library_entry_id": { "type": "string" }, "times_cooked": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "library_entry_id", "times_cooked", "items" ], "type": "object" }, "CookingInput": { "additionalProperties": false, "properties": { "cooked_on": { "description": "Defaults to today", "format": "date", "type": "string" }, "cooked_time": { "description": "Optional local clock time; omitted for day-only history", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, "note": { "maxLength": 10000, "type": "string" }, "scale": { "maxLength": 128, "pattern": "^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "session_id": { "description": "Cooking session key used to make retries idempotent", "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } }, "type": "object" }, "CookingRecord": { "additionalProperties": true, "properties": { "cooked_on": { "format": "date", "type": "string" }, "cooked_time": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "note": { "maxLength": 10000, "type": "string" }, "scale": { "description": "Batch actually made, as a factor of the recipe as written", "maxLength": 128, "pattern": "^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "session_id": { "type": "string" } }, "required": [ "id", "cooked_on", "created_at" ], "type": "object" }, "Create-grocery-itemsRequest": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/Addition" }, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Create-import-jobRequest": { "additionalProperties": false, "properties": { "file_content": { "contentEncoding": "base64", "type": "string" }, "filename": { "maxLength": 255, "type": "string" }, "kind": { "enum": [ "url", "file", "text" ], "type": "string" }, "on_duplicate": { "default": "reject", "enum": [ "reject", "skip" ], "type": "string" }, "policy": { "default": "preview-only", "enum": [ "preview-only", "require-no-warnings", "allow-warnings" ], "type": "string" }, "text": { "maxLength": 1000000, "type": "string" }, "url": { "maxLength": 8192, "type": "string" } }, "required": [ "kind" ], "type": "object" }, "Create-instance-webhook-redeliveryResponse": { "additionalProperties": true, "properties": { "queued": { "type": "boolean" } }, "required": [ "queued" ], "type": "object" }, "Create-webhook-redeliveryResponse": { "additionalProperties": true, "properties": { "queued": { "type": "boolean" } }, "required": [ "queued" ], "type": "object" }, "CreateLibraryRequest": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateUserRequest": { "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "library_id": { "type": "string" }, "login": { "type": "string" }, "password": { "type": "string", "writeOnly": true }, "role": { "enum": [ "viewer", "editor", "owner" ], "type": "string" } }, "required": [ "login", "display_name", "password" ], "type": "object" }, "CredentialLoginResponse": { "additionalProperties": true, "properties": { "csrf_token": { "type": "string" }, "recovery_authenticated": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token", "recovery_authenticated" ], "type": "object" }, "CustomerStorageStatus": { "additionalProperties": false, "properties": { "available_bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "available_inodes": { "format": "int64", "minimum": 0, "type": "integer" }, "hosted": { "type": "boolean" }, "limit_bytes": { "format": "int64", "type": "integer" }, "state": { "enum": [ "normal", "warning", "limited", "unknown" ], "type": "string" }, "support_url": { "type": "string" }, "used_bytes": { "format": "int64", "type": "integer" } }, "required": [ "hosted", "state" ], "type": "object" }, "DeleteAccountRequest": { "additionalProperties": false, "properties": { "confirmation": { "enum": [ "DELETE" ], "type": "string" }, "password": { "type": "string", "writeOnly": true } }, "required": [ "confirmation" ], "type": "object" }, "DeleteLibraryRequest": { "additionalProperties": false, "properties": { "confirmation": { "type": "string" } }, "required": [ "confirmation" ], "type": "object" }, "Delivery": { "additionalProperties": true, "properties": { "attempts": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "last_code": { "type": "string" }, "next_attempt_at": { "format": "date-time", "type": "string" }, "state": { "type": "string" }, "subscription_id": { "type": "string" } }, "required": [ "id", "subscription_id", "event_id", "event_type", "state", "created_at", "attempts" ], "type": "object" }, "Detail": { "additionalProperties": true, "properties": { "attempts": { "items": { "$ref": "#/components/schemas/Attempt" }, "type": [ "array", "null" ] }, "delivery": { "$ref": "#/components/schemas/Delivery" } }, "required": [ "delivery", "attempts" ], "type": "object" }, "DietaryClaim": { "additionalProperties": false, "properties": { "condition": { "description": "Authored limit on the claim; a conditional claim is never shown or filtered as unconditional", "maxLength": 1000000, "type": "string" }, "diet": { "description": "Normalized subject; absent when the diet has none", "enum": [ "diabetic", "gluten_free", "halal", "hindu", "kosher", "low_calorie", "low_fat", "low_lactose", "low_salt", "vegan", "vegetarian" ], "type": "string" }, "suitability": { "enum": [ "suitable", "unsuitable" ], "type": "string" }, "text": { "description": "The complete authored statement", "maxLength": 1000000, "minLength": 1, "type": "string" }, "variant_ref": { "description": "The variant the claim describes, which it does not extend to the recipe as written", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": [ "text", "suitability" ], "type": "object" }, "DraftTranslationInputBody": { "additionalProperties": false, "properties": { "copy_content": { "description": "Start from a copy of this recipe's content, as ordinary editable text in its original language", "type": "boolean" }, "language": { "description": "BCP 47 tag of the new rendition's language", "maxLength": 255, "minLength": 2, "type": "string" }, "title": { "maxLength": 1000, "type": "string" } }, "required": [ "language" ], "type": "object" }, "DurationExpression": { "additionalProperties": false, "properties": { "approximate": { "type": "boolean" }, "max": { "maxLength": 100, "pattern": "^P(?:[0-9]+Y)?(?:[0-9]+M)?(?:[0-9]+W)?(?:[0-9]+D)?(?:T(?:[0-9]+H)?(?:[0-9]+M)?(?:[0-9]+S)?)?$", "type": "string" }, "min": { "maxLength": 100, "pattern": "^P(?:[0-9]+Y)?(?:[0-9]+M)?(?:[0-9]+W)?(?:[0-9]+D)?(?:T(?:[0-9]+H)?(?:[0-9]+M)?(?:[0-9]+S)?)?$", "type": "string" }, "source_text": { "maxLength": 1000, "type": "string" }, "text": { "description": "Opaque wording such as overnight; excludes a value or a range", "maxLength": 1000, "type": "string" }, "value": { "maxLength": 100, "pattern": "^P(?:[0-9]+Y)?(?:[0-9]+M)?(?:[0-9]+W)?(?:[0-9]+D)?(?:T(?:[0-9]+H)?(?:[0-9]+M)?(?:[0-9]+S)?)?$", "type": "string" } }, "type": "object" }, "EmptyTrashInputBody": { "additionalProperties": false, "properties": { "books": { "description": "Trashed books reviewed for permanent removal", "items": { "$ref": "#/components/schemas/EmptyTrashTarget" }, "maxItems": 1000, "type": [ "array", "null" ] }, "recipes": { "description": "Trashed recipes reviewed for permanent removal", "items": { "$ref": "#/components/schemas/EmptyTrashTarget" }, "maxItems": 1000, "type": [ "array", "null" ] } }, "type": "object" }, "EmptyTrashTarget": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "id", "revision" ], "type": "object" }, "Entry": { "additionalProperties": true, "properties": { "amount": { "maxLength": 100, "type": "string" }, "id": { "type": "string" }, "location": { "maxLength": 100, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "note": { "maxLength": 2000, "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "semantic_id": { "maxLength": 200, "type": "string" }, "unit": { "maxLength": 100, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "name", "revision", "updated_at", "updated_by" ], "type": "object" }, "Equipment": { "additionalProperties": false, "properties": { "name": { "description": "Authored equipment description; not a normalized registry identity", "maxLength": 1000, "minLength": 1, "type": "string" }, "note": { "maxLength": 1000000, "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity", "description": "Authored equipment count or measure; does not automatically scale with recipe yield" } }, "required": [ "name" ], "type": "object" }, "ErrorDetail": { "additionalProperties": true, "properties": { "location": { "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'", "type": "string" }, "message": { "description": "Error message text", "type": "string" }, "value": { "description": "The value at the given location" } }, "type": "object" }, "ErrorModel": { "additionalProperties": true, "properties": { "code": { "description": "Stable application error code; clients may also use the problem type suffix.", "type": "string" }, "detail": { "description": "A human-readable explanation specific to this occurrence of the problem.", "examples": [ "Property foo is required but is missing." ], "type": "string" }, "errors": { "description": "Optional list of individual error details", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem.", "examples": [ "https://example.com/error-log/abc123" ], "format": "uri", "type": "string" }, "params": { "additionalProperties": true, "description": "Structured context for the stable error code.", "type": "object" }, "status": { "description": "HTTP status code", "examples": [ 400 ], "format": "int64", "type": "integer" }, "title": { "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.", "examples": [ "Bad Request" ], "type": "string" }, "type": { "default": "about:blank", "description": "A URI reference to human-readable documentation for the error.", "examples": [ "https://example.com/errors/example" ], "format": "uri", "type": "string" }, "violations": { "items": { "properties": { "code": { "type": "string" }, "location": { "type": "string" }, "params": { "additionalProperties": true, "type": "object" } }, "required": [ "code", "location" ], "type": "object" }, "type": "array" } }, "type": "object" }, "ExportBundleInput": { "additionalProperties": false, "properties": { "recipes": { "description": "Library entries to export, in the order they should appear in the bundle", "items": { "type": "string" }, "maxItems": 250, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "recipes" ], "type": "object" }, "ExportInput": { "additionalProperties": false, "properties": { "format": { "enum": [ "sref", "sref-bundle" ], "type": "string" }, "library": { "type": "boolean" }, "recipes": { "items": { "type": "string" }, "maxItems": 10000, "type": [ "array", "null" ] } }, "required": [ "format" ], "type": "object" }, "Facet": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "course", "cuisine", "method", "dietary" ], "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "value": { "type": "string" } }, "required": [ "id", "kind", "value", "revision", "created_at", "updated_at" ], "type": "object" }, "FacetInput": { "additionalProperties": false, "properties": { "kind": { "enum": [ "course", "cuisine", "method", "dietary" ], "type": "string" }, "value": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "kind", "value" ], "type": "object" }, "FacetsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/Facet" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Grant": { "additionalProperties": true, "properties": { "secret": { "type": "string" }, "subscription": { "$ref": "#/components/schemas/Subscription" } }, "required": [ "subscription", "secret" ], "type": "object" }, "GroupMapping": { "additionalProperties": false, "properties": { "group": { "type": "string" }, "id": { "type": "string" }, "library_id": { "type": "string" }, "provider_id": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "provider_id", "group", "library_id", "role" ], "type": "object" }, "GroupMappingsResponse": { "additionalProperties": true, "properties": { "mappings": { "items": { "$ref": "#/components/schemas/GroupMapping" }, "type": [ "array", "null" ] } }, "required": [ "mappings" ], "type": "object" }, "HealthOutputBody": { "additionalProperties": true, "properties": { "status": { "enum": [ "ok" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ImportDiagnostic": { "additionalProperties": true, "properties": { "area": { "type": "string" }, "class": { "type": "string" }, "code": { "type": "string" }, "count": { "format": "int64", "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "class", "message", "count" ], "type": "object" }, "ImportDiagnosticTarget": { "additionalProperties": true, "properties": { "action": { "type": "string" }, "evidence": { "type": "string" }, "field": { "type": "string" }, "object_id": { "type": "string" }, "preserved": { "type": "string" }, "resolution": { "$ref": "#/components/schemas/ImportResolutionDescriptor" } }, "type": "object" }, "ImportEventResource": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "baseline_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "content_sha256": { "type": "string" }, "diagnostics": { "items": { "$ref": "#/components/schemas/ImportDiagnostic" }, "type": [ "array", "null" ] }, "display_name": { "type": "string" }, "entry_id": { "type": "string" }, "id": { "type": "string" }, "importer": { "type": "string" }, "importer_version": { "type": "string" }, "input_kind": { "type": "string" }, "job_id": { "type": "string" }, "operation": { "type": "string" }, "recipe_id": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "source_id": { "type": "string" }, "source_snapshot": { "$ref": "#/components/schemas/RecipeDocument" }, "source_url": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" } }, "required": [ "id", "entry_id", "recipe_id", "revision", "timestamp", "operation", "baseline_revision", "content_sha256", "importer", "importer_version", "input_kind", "display_name", "diagnostics" ], "type": "object" }, "ImportHistoryOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportEventResource" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" } }, "required": [ "items", "limit", "offset" ], "type": "object" }, "ImportInput": { "additionalProperties": false, "properties": { "on_duplicate": { "description": "Defaults to reject, which changes nothing and reports what was already here", "enum": [ "reject", "skip", "replace" ], "type": "string" }, "recipes": { "description": "SREF recipe documents, each carrying its own sref version member", "items": {}, "maxItems": 500, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "recipes" ], "type": "object" }, "ImportJobDiagnostic": { "additionalProperties": true, "properties": { "area": { "type": "string" }, "class": { "enum": [ "blocking", "actionable", "informational" ], "type": "string" }, "code": { "type": "string" }, "count": { "format": "int64", "minimum": 1, "type": "integer" }, "message": { "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/ImportDiagnosticTarget" }, "type": [ "array", "null" ] } }, "required": [ "code", "class", "area", "message", "count" ], "type": "object" }, "ImportJobDiagnosticSummary": { "additionalProperties": true, "properties": { "area": { "type": "string" }, "class": { "enum": [ "blocking", "actionable", "informational" ], "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "occurrences": { "format": "int64", "minimum": 1, "type": "integer" }, "recipes": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "code", "class", "area", "message", "occurrences", "recipes" ], "type": "object" }, "ImportJobItemResource": { "additionalProperties": true, "properties": { "deferred_assets": { "description": "Photographs not fetched yet whose addresses the recipe retains", "format": "int64", "minimum": 0, "type": "integer" }, "diagnostics": { "items": { "$ref": "#/components/schemas/ImportJobDiagnostic" }, "type": [ "array", "null" ] }, "dropped_assets": { "description": "Photographs this recipe names that could not be retrieved and were left out", "format": "int64", "minimum": 0, "type": "integer" }, "error": { "type": "string" }, "filename": { "type": "string" }, "finished_at": { "format": "date-time", "type": "string" }, "import_event_id": { "type": "string" }, "library_entry_id": { "type": "string" }, "outcome": { "enum": [ "created", "replaced", "skipped" ], "type": "string" }, "position": { "format": "int64", "minimum": 0, "type": "integer" }, "recipe_id": { "type": "string" }, "review_required": { "type": "boolean" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "source_url": { "type": "string" }, "started_at": { "format": "date-time", "type": "string" }, "state": { "enum": [ "pending", "running", "imported", "skipped", "failed", "cancelled" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "position", "title", "state", "review_required", "dropped_assets", "deferred_assets" ], "type": "object" }, "ImportJobProgress": { "additionalProperties": true, "properties": { "cancelled": { "format": "int64", "minimum": 0, "type": "integer" }, "current_batch": { "description": "The one-based batch being processed, zero before work starts", "format": "int64", "minimum": 0, "type": "integer" }, "diagnostic_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "diagnostics": { "items": { "$ref": "#/components/schemas/ImportJobDiagnosticSummary" }, "type": [ "array", "null" ] }, "failed": { "format": "int64", "minimum": 0, "type": "integer" }, "finished": { "format": "int64", "minimum": 0, "type": "integer" }, "imported": { "format": "int64", "minimum": 0, "type": "integer" }, "informational_preservation": { "format": "int64", "minimum": 0, "type": "integer" }, "pending": { "format": "int64", "minimum": 0, "type": "integer" }, "resumable": { "description": "Unfinished recipes Savorum still holds enough of to run again", "format": "int64", "minimum": 0, "type": "integer" }, "review_required": { "format": "int64", "minimum": 0, "type": "integer" }, "running": { "format": "int64", "minimum": 0, "type": "integer" }, "skipped": { "format": "int64", "minimum": 0, "type": "integer" }, "total": { "format": "int64", "minimum": 0, "type": "integer" }, "total_batches": { "format": "int64", "minimum": 1, "type": "integer" }, "without_diagnostics": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "total", "pending", "running", "imported", "skipped", "failed", "cancelled", "review_required", "resumable", "informational_preservation", "without_diagnostics", "diagnostic_occurrences", "diagnostics", "finished", "current_batch", "total_batches" ], "type": "object" }, "ImportJobResource": { "additionalProperties": true, "properties": { "cancellation_requested_at": { "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error": { "type": "string" }, "finished_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "importer": { "description": "The source formats this import came from, in the reader's words", "type": "string" }, "lead_title": { "description": "The title of this job's first recipe, for naming the import by what it brought", "type": "string" }, "on_duplicate": { "enum": [ "reject", "skip", "replace" ], "type": "string" }, "progress": { "$ref": "#/components/schemas/ImportJobProgress" }, "resolution_decisions": { "items": { "$ref": "#/components/schemas/ImportResolutionDecision" }, "type": [ "array", "null" ] }, "source": { "description": "What was chosen: a filename, several, or the format when there was no file", "type": "string" }, "started_at": { "format": "date-time", "type": "string" }, "state": { "enum": [ "pending", "running", "completed", "completed-with-errors", "cancelled", "failed", "interrupted" ], "type": "string" }, "total_items": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "id", "importer", "source", "state", "on_duplicate", "total_items", "created_at", "progress", "resolution_decisions" ], "type": "object" }, "ImportJobStartInput": { "additionalProperties": false, "properties": { "item_ids": { "items": { "type": "string" }, "maxItems": 500, "type": [ "array", "null" ] }, "on_duplicate": { "enum": [ "reject", "skip", "replace" ], "type": "string" }, "resolutions": { "items": { "$ref": "#/components/schemas/ImportPreviewResolutionInput" }, "maxItems": 500, "type": [ "array", "null" ] }, "retain_source_item_ids": { "description": "Uploaded preview item IDs whose original files should be retained", "items": { "type": "string" }, "maxItems": 500, "type": [ "array", "null" ] } }, "type": "object" }, "ImportJobStartResponse": { "additionalProperties": true, "properties": { "job": { "$ref": "#/components/schemas/ImportJobResource" }, "remaining": { "$ref": "#/components/schemas/ImportPreviewResponse" } }, "required": [ "job" ], "type": "object" }, "ImportOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportedRecipe" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "ImportPreviewAnalysis": { "additionalProperties": true, "properties": { "matches": { "items": { "$ref": "#/components/schemas/ImportPreviewMatch" }, "type": [ "array", "null" ] }, "status": { "enum": [ "new", "definite-match", "likely-duplicate", "ambiguous" ], "type": "string" } }, "required": [ "status", "matches" ], "type": "object" }, "ImportPreviewAssets": { "additionalProperties": true, "properties": { "available": { "format": "int64", "minimum": 0, "type": "integer" }, "deferred": { "format": "int64", "minimum": 0, "type": "integer" }, "discovered": { "format": "int64", "minimum": 0, "type": "integer" }, "failed": { "format": "int64", "minimum": 0, "type": "integer" }, "preview_url": { "description": "Retrieves this recipe's leading photograph on demand; answers 404 with a problem type saying whether it is pending or unavailable", "type": "string" }, "unavailable": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "discovered", "available", "deferred", "failed", "unavailable" ], "type": "object" }, "ImportPreviewCommitInput": { "additionalProperties": false, "properties": { "item_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "on_duplicate": { "type": "string" }, "resolutions": { "items": { "$ref": "#/components/schemas/ImportPreviewResolutionInput" }, "type": [ "array", "null" ] }, "retain_source_item_ids": { "description": "Uploaded preview item IDs whose original files should be retained with the imported revision", "items": { "type": "string" }, "maxItems": 500, "type": [ "array", "null" ] } }, "type": "object" }, "ImportPreviewCommitResponse": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportedRecipe" }, "type": [ "array", "null" ] }, "remaining": { "$ref": "#/components/schemas/ImportPreviewResponse" } }, "required": [ "items" ], "type": "object" }, "ImportPreviewDiagnostic": { "additionalProperties": true, "properties": { "area": { "type": "string" }, "class": { "enum": [ "blocking", "actionable", "informational" ], "type": "string" }, "code": { "type": "string" }, "count": { "format": "int64", "minimum": 1, "type": "integer" }, "message": { "type": "string" }, "severity": { "enum": [ "info", "warning", "error" ], "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/ImportDiagnosticTarget" }, "type": [ "array", "null" ] } }, "required": [ "code", "class", "severity", "area", "message", "count" ], "type": "object" }, "ImportPreviewItem": { "additionalProperties": true, "properties": { "already_here": { "type": "boolean" }, "analysis": { "$ref": "#/components/schemas/ImportPreviewAnalysis" }, "assets": { "$ref": "#/components/schemas/ImportPreviewAssets" }, "can_commit": { "type": "boolean" }, "diagnostics": { "items": { "$ref": "#/components/schemas/ImportPreviewDiagnostic" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "recipe": { "$ref": "#/components/schemas/ImportPreviewRecipe" }, "source": { "$ref": "#/components/schemas/ImportPreviewSource" } }, "required": [ "id", "recipe", "source", "analysis", "diagnostics", "assets", "already_here", "can_commit" ], "type": "object" }, "ImportPreviewMatch": { "additionalProperties": true, "properties": { "authors": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "entry_id": { "type": "string" }, "evidence": { "enum": [ "source-identity", "canonical-url", "portable-id", "similarity" ], "type": "string" }, "ingredient_count": { "format": "int64", "minimum": 0, "type": "integer" }, "recipe_id": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "score": { "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "title": { "type": "string" }, "yield": { "type": "string" } }, "required": [ "entry_id", "revision", "recipe_id", "title", "authors", "ingredient_count", "evidence", "score" ], "type": "object" }, "ImportPreviewRecipe": { "additionalProperties": true, "properties": { "description": { "type": "string" }, "ingredient_count": { "format": "int64", "minimum": 0, "type": "integer" }, "ingredients": { "items": { "$ref": "#/components/schemas/ImportPreviewSection" }, "type": [ "array", "null" ] }, "instructions": { "items": { "$ref": "#/components/schemas/ImportPreviewSection" }, "type": [ "array", "null" ] }, "step_count": { "format": "int64", "minimum": 0, "type": "integer" }, "title": { "type": "string" }, "yield": { "type": "string" } }, "required": [ "title", "ingredient_count", "step_count" ], "type": "object" }, "ImportPreviewResolutionInput": { "additionalProperties": false, "properties": { "action": { "enum": [ "separate", "update", "skip" ], "type": "string" }, "item_id": { "type": "string" }, "target_entry_id": { "type": "string" } }, "required": [ "item_id", "action" ], "type": "object" }, "ImportPreviewResponse": { "additionalProperties": true, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ImportPreviewItem" }, "type": [ "array", "null" ] }, "preview_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "resolution_decisions": { "items": { "$ref": "#/components/schemas/MeasurementResolutionDecision" }, "type": [ "array", "null" ] }, "resolution_groups": { "items": { "$ref": "#/components/schemas/MeasurementResolutionGroup" }, "type": [ "array", "null" ] }, "resolution_profiles": { "items": { "$ref": "#/components/schemas/MeasurementResolutionProfile" }, "type": [ "array", "null" ] } }, "required": [ "id", "expires_at", "preview_revision", "items", "resolution_decisions", "resolution_groups", "resolution_profiles" ], "type": "object" }, "ImportPreviewSection": { "additionalProperties": true, "properties": { "items": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "title": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "ImportPreviewSource": { "additionalProperties": true, "properties": { "attribution": { "type": "string" }, "can_retain": { "description": "The uploaded original can be retained explicitly when this preview item is committed", "type": "boolean" }, "extracted_text": { "description": "Text extracted from a document upload, editable before commit", "type": "string" }, "filename": { "type": "string" }, "format_id": { "type": "string" }, "format_name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "format_id", "format_name", "can_retain" ], "type": "object" }, "ImportPreviewTextInput": { "additionalProperties": false, "properties": { "text": { "type": "string" } }, "required": [ "text" ], "type": "object" }, "ImportResolutionDecision": { "additionalProperties": true, "properties": { "affected_ingredient_count": { "format": "int64", "minimum": 0, "type": "integer" }, "affected_occurrence_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "affected_recipe_count": { "format": "int64", "minimum": 0, "type": "integer" }, "convention": { "type": "string" }, "convention_unit_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "decision_scope": { "type": "string" }, "excluded_item_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "excluded_occurrence_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "impact_digest": { "type": "string" }, "interpretation_kind": { "type": "string" }, "original_actionable_count": { "format": "int64", "minimum": 0, "type": "integer" }, "parser_version": { "type": "string" }, "resolution_kind": { "type": "string" }, "resulting_actionable_count": { "format": "int64", "minimum": 0, "type": "integer" }, "scope_ingredient_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "scope_occurrence_keys": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "unit_id": { "type": "string" }, "unit_registry_version": { "type": "string" } }, "required": [ "resolution_kind", "interpretation_kind", "decision_scope", "affected_ingredient_count", "parser_version", "unit_registry_version", "affected_occurrence_ids", "affected_recipe_count", "original_actionable_count", "resulting_actionable_count", "impact_digest" ], "type": "object" }, "ImportResolutionDescriptor": { "additionalProperties": true, "properties": { "authored_form": { "type": "string" }, "candidate_unit_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "resolution_key": { "type": "string" }, "source_end": { "format": "int64", "minimum": 0, "type": "integer" }, "source_start": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "id", "kind", "authored_form", "source_start", "source_end", "candidate_unit_ids", "resolution_key" ], "type": "object" }, "ImportURLInput": { "additionalProperties": false, "properties": { "on_duplicate": { "enum": [ "reject", "skip", "replace" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "ImportedCookCountBaseline": { "additionalProperties": true, "properties": { "count": { "format": "int64", "minimum": 0, "type": "integer" }, "source": { "type": "string" }, "source_key": { "type": "string" } }, "required": [ "count", "source", "source_key" ], "type": "object" }, "ImportedRecipe": { "additionalProperties": true, "properties": { "deferred_assets": { "description": "Images not fetched yet whose addresses the recipe retains", "format": "int64", "minimum": 0, "type": "integer" }, "dropped_assets": { "description": "Images the recipe named that could not be retrieved and were left out", "format": "int64", "minimum": 0, "type": "integer" }, "import_event_id": { "type": "string" }, "library_entry_id": { "type": "string" }, "outcome": { "enum": [ "created", "replaced", "skipped" ], "type": "string" }, "recipe_id": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "title": { "type": "string" }, "warnings": { "description": "What the import had to work around, in the reader's words", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "library_entry_id", "recipe_id", "title", "revision", "outcome", "dropped_assets", "deferred_assets" ], "type": "object" }, "Ingredient": { "additionalProperties": false, "properties": { "alternatives": { "description": "Ordered complete authored branches; nested choices are refused", "items": { "$ref": "#/components/schemas/Ingredient" }, "maxItems": 100, "minItems": 2, "type": [ "array", "null" ] }, "id": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "name": { "maxLength": 1000, "minLength": 1, "type": "string" }, "normalization": { "$ref": "#/components/schemas/Normalization" }, "note": { "maxLength": 1000000, "type": "string" }, "optional": { "description": "The author sanctioned leaving this occurrence out. It belongs to the occurrence, never to the ingredient: the same thing may be optional in a garnish section and required by the method", "type": "boolean" }, "package_size": { "$ref": "#/components/schemas/SimpleQuantity" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "recipe": { "$ref": "#/components/schemas/RecipeDependency", "description": "The recipe that makes this ingredient, as the source identified it. Its content is not included" }, "relation": { "enum": [ "or", "and_or", "preferred" ], "type": "string" }, "source_text": { "maxLength": 1000000, "type": "string" }, "temperature": { "$ref": "#/components/schemas/Temperature" } }, "required": [ "id" ], "type": "object" }, "IngredientSection": { "additionalProperties": false, "properties": { "id": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "ingredients": { "items": { "$ref": "#/components/schemas/Ingredient" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "title": { "maxLength": 1000, "type": "string" } }, "required": [ "id", "ingredients" ], "type": "object" }, "IngredientUse": { "additionalProperties": false, "properties": { "ingredient_ref": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" } }, "required": [ "ingredient_ref" ], "type": "object" }, "Input": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "event_types": { "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "type": [ "array", "null" ] }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "url": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "name", "url", "event_types", "enabled" ], "type": "object" }, "InstanceConfiguration": { "additionalProperties": true, "properties": { "capabilities": { "$ref": "#/components/schemas/InstanceConfigurationCapabilitiesStruct" }, "default_locale": { "maxLength": 100, "type": "string" }, "default_measurement": { "enum": [ "original", "metric", "us", "au" ], "type": "string" }, "display_name": { "maxLength": 100, "type": "string" }, "import_policy": { "$ref": "#/components/schemas/InstanceConfigurationImportPolicyStruct" }, "print_defaults": { "$ref": "#/components/schemas/InstanceConfigurationPrintDefaultsStruct" }, "public_url": { "format": "uri", "type": "string" } }, "required": [ "display_name", "default_locale", "default_measurement", "import_policy", "print_defaults", "capabilities" ], "type": "object" }, "InstanceConfigurationCapabilitiesStruct": { "additionalProperties": true, "properties": { "authentication": { "description": "False until an authentication system is configured", "type": "boolean" }, "mutable_instance_settings": { "description": "Whether this build exposes a mutable instance-settings API", "type": "boolean" } }, "required": [ "mutable_instance_settings", "authentication" ], "type": "object" }, "InstanceConfigurationImportPolicyStruct": { "additionalProperties": true, "properties": { "allow_external_fetch": { "type": "boolean" }, "allow_file_uploads": { "type": "boolean" } }, "required": [ "allow_external_fetch", "allow_file_uploads" ], "type": "object" }, "InstanceConfigurationPrintDefaultsStruct": { "additionalProperties": true, "properties": { "image": { "enum": [ "automatic", "include", "omit" ], "type": "string" }, "page_size": { "enum": [ "automatic", "letter", "a4" ], "type": "string" } }, "required": [ "page_size", "image" ], "type": "object" }, "InstructionSection": { "additionalProperties": false, "properties": { "id": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "steps": { "items": { "$ref": "#/components/schemas/Step" }, "maxItems": 10000, "minItems": 1, "type": [ "array", "null" ] }, "title": { "maxLength": 1000, "type": "string" } }, "required": [ "id", "steps" ], "type": "object" }, "InterfaceLocale": { "additionalProperties": true, "properties": { "status": { "enum": [ "supported", "preview" ], "type": "string" }, "tag": { "description": "BCP 47 tag", "type": "string" } }, "required": [ "tag", "status" ], "type": "object" }, "Invitation": { "additionalProperties": true, "properties": { "accepted_at": { "format": "int64", "type": [ "integer", "null" ] }, "created_at": { "format": "int64", "type": "integer" }, "creator": { "type": "string" }, "expires_at": { "format": "int64", "type": "integer" }, "hint": { "type": "string" }, "id": { "type": "string" }, "library_id": { "type": "string" }, "revoked_at": { "format": "int64", "type": [ "integer", "null" ] }, "role": { "type": "string" } }, "required": [ "id", "library_id", "role", "hint", "creator", "created_at", "expires_at", "accepted_at", "revoked_at" ], "type": "object" }, "InvitationAcceptRequest": { "additionalProperties": false, "properties": { "token": { "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" }, "InvitationCreateRequest": { "additionalProperties": false, "properties": { "days": { "format": "int64", "maximum": 30, "minimum": 1, "type": "integer" }, "hint": { "type": "string" }, "role": { "enum": [ "viewer", "editor", "owner" ], "type": "string" } }, "required": [ "role" ], "type": "object" }, "InvitationCreateResponse": { "additionalProperties": true, "properties": { "invitation": { "$ref": "#/components/schemas/Invitation" }, "token": { "type": "string" } }, "required": [ "invitation", "token" ], "type": "object" }, "InvitationListResponse": { "additionalProperties": true, "properties": { "invitations": { "items": { "$ref": "#/components/schemas/Invitation" }, "type": [ "array", "null" ] } }, "required": [ "invitations" ], "type": "object" }, "InvitationRegisterRequest": { "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "login": { "type": "string" }, "password": { "type": "string", "writeOnly": true }, "token": { "type": "string", "writeOnly": true } }, "required": [ "token", "login", "display_name", "password" ], "type": "object" }, "JobResource": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "download_url": { "type": "string" }, "expires_at": { "type": "string" }, "finished": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "import_job_id": { "type": "string" }, "kind": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "state": { "type": "string" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "id", "kind", "state", "revision", "created_at", "finished", "total" ], "type": "object" }, "JobResultsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BulkItemResult" }, "type": [ "array", "null" ] }, "next_offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "next_offset", "items", "total" ], "type": "object" }, "LibrariesResponse": { "additionalProperties": true, "properties": { "libraries": { "items": { "$ref": "#/components/schemas/Library" }, "type": [ "array", "null" ] } }, "required": [ "libraries" ], "type": "object" }, "Library": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "name", "role" ], "type": "object" }, "LibraryBookSummary": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "kind": { "enum": [ "personal", "publication" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "kind", "title" ], "type": "object" }, "LibraryEntry": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "id": { "description": "Identifier of this entry in the local Savorum library", "type": "string" }, "recipe": { "$ref": "#/components/schemas/RecipeDocument" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "time_summary": { "$ref": "#/components/schemas/TimeSummary" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "recipe", "time_summary", "revision", "created_at", "updated_at" ], "type": "object" }, "LinkTranslationInputBody": { "additionalProperties": false, "properties": { "counterpart": { "description": "Library entry of the other rendition", "minLength": 1, "type": "string" }, "relation": { "description": "How the counterpart relates to this recipe", "enum": [ "original", "translation", "alternate" ], "type": "string" } }, "required": [ "counterpart", "relation" ], "type": "object" }, "ListImportJobItemsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportJobItemResource" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ListImportJobsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportJobResource" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ListRecipeAuthorsOutputBody": { "additionalProperties": true, "properties": { "candidate_limit_reached": { "description": "Typo candidate retrieval exceeded 128 names; additional suggestions may exist", "type": "boolean" }, "has_more": { "description": "Matching names in the selected tier exceed the requested limit", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/RecipeAuthorCandidate" }, "type": [ "array", "null" ] } }, "required": [ "items", "has_more", "candidate_limit_reached" ], "type": "object" }, "ListRecipeReferencesOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/RecipeReference" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "ListRecipesOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/RecipeSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ListRevisionsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/RecipeRevisionSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" } }, "required": [ "items", "limit", "offset" ], "type": "object" }, "LoginRequest": { "additionalProperties": false, "properties": { "login": { "type": "string" }, "password": { "type": "string", "writeOnly": true } }, "required": [ "login", "password" ], "type": "object" }, "LoginResponse": { "additionalProperties": true, "properties": { "csrf_token": { "type": "string" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token" ], "type": "object" }, "LookupInputBody": { "additionalProperties": false, "properties": { "ids": { "items": { "type": "string" }, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "ids" ], "type": "object" }, "LookupOutputBookSelectionSummaryBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/BookSelectionSummary" }, "type": [ "array", "null" ] }, "unresolved_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "items", "unresolved_ids" ], "type": "object" }, "LookupOutputRecipeSummaryBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/RecipeSummary" }, "type": [ "array", "null" ] }, "unresolved_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "items", "unresolved_ids" ], "type": "object" }, "ManagedUser": { "additionalProperties": true, "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ], "type": "object" }, "Meal": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "readOnly": true, "type": "string" }, "created_by_name": { "readOnly": true, "type": "string" }, "date": { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" }, "dishes": { "items": { "$ref": "#/components/schemas/MealDish" }, "maxItems": 50, "minItems": 1, "type": [ "array", "null" ] }, "display_title": { "readOnly": true, "type": "string" }, "id": { "type": "string" }, "meal_type": { "enum": [ "", "breakfast", "lunch", "dinner", "snack" ], "type": "string" }, "name": { "maxLength": 200, "type": "string" }, "notes": { "maxLength": 10000, "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "skipped": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "readOnly": true, "type": "string" }, "updated_by_name": { "readOnly": true, "type": "string" } }, "required": [ "id", "display_title", "skipped", "dishes", "revision", "created_at", "updated_at" ], "type": "object" }, "MealDish": { "additionalProperties": false, "properties": { "display_name": { "maxLength": 200, "minLength": 1, "type": "string" }, "entry_id": { "type": "string" }, "id": { "type": "string" }, "leftover_of": { "maxLength": 201, "type": "string" }, "notes": { "maxLength": 5000, "type": "string" }, "plain_items": { "description": "Only for a dish without entry_id.", "items": { "$ref": "#/components/schemas/MealPlainItem" }, "maxItems": 100, "type": [ "array", "null" ] }, "recipe_image_url": { "readOnly": true, "type": "string" }, "recipe_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "recipe_status": { "enum": [ "available", "trashed", "removed" ], "readOnly": true, "type": "string" }, "scale": { "maxLength": 100, "type": "string" }, "shopping_choices": { "items": { "type": "string" }, "readOnly": true, "type": [ "array", "null" ] } }, "required": [ "display_name" ], "type": "object" }, "MealInput": { "additionalProperties": false, "properties": { "date": { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" }, "dishes": { "items": { "$ref": "#/components/schemas/MealDish" }, "maxItems": 50, "minItems": 1, "type": [ "array", "null" ] }, "meal_type": { "enum": [ "", "breakfast", "lunch", "dinner", "snack" ], "type": "string" }, "name": { "maxLength": 200, "type": "string" }, "notes": { "maxLength": 10000, "type": "string" }, "skipped": { "type": "boolean" } }, "required": [ "dishes" ], "type": "object" }, "MealPlacementInput": { "additionalProperties": false, "properties": { "date": { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" }, "meal_type": { "enum": [ "", "breakfast", "lunch", "dinner", "snack" ], "type": "string" } }, "type": "object" }, "MealPlainItem": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "quantity": { "maxLength": 200, "type": "string" } }, "required": [ "name" ], "type": "object" }, "MealsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/Meal" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "MeasurementResolutionChoice": { "additionalProperties": true, "properties": { "convention": { "type": "string" }, "convention_label": { "type": "string" }, "label": { "type": "string" }, "magnitude": { "type": "string" }, "unit_id": { "type": "string" } }, "required": [ "unit_id", "label", "convention" ], "type": "object" }, "MeasurementResolutionDecision": { "additionalProperties": true, "properties": { "authored_forms": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "candidate_unit_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "choices": { "items": { "$ref": "#/components/schemas/MeasurementResolutionChoice" }, "type": [ "array", "null" ] }, "examples": { "items": { "$ref": "#/components/schemas/MeasurementResolutionExample" }, "type": [ "array", "null" ] }, "group_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "ingredients": { "format": "int64", "minimum": 0, "type": "integer" }, "measure_label": { "type": "string" }, "occurrences": { "format": "int64", "minimum": 1, "type": "integer" }, "recipes": { "format": "int64", "minimum": 1, "type": "integer" }, "source_label": { "type": "string" } }, "required": [ "id", "measure_label", "authored_forms", "group_ids", "occurrences", "ingredients", "recipes", "candidate_unit_ids", "choices", "examples" ], "type": "object" }, "MeasurementResolutionExample": { "additionalProperties": true, "properties": { "after": { "type": "string" }, "before": { "type": "string" }, "recipe_title": { "type": "string" }, "source_text": { "type": "string" } }, "required": [ "recipe_title", "source_text", "before" ], "type": "object" }, "MeasurementResolutionGroup": { "additionalProperties": true, "properties": { "authored_form": { "type": "string" }, "candidate_unit_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "choices": { "items": { "$ref": "#/components/schemas/MeasurementResolutionChoice" }, "type": [ "array", "null" ] }, "examples": { "items": { "$ref": "#/components/schemas/MeasurementResolutionExample" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "ingredients": { "format": "int64", "minimum": 0, "type": "integer" }, "kind": { "enum": [ "unit_alias" ], "type": "string" }, "occurrences": { "format": "int64", "minimum": 1, "type": "integer" }, "recipes": { "format": "int64", "minimum": 1, "type": "integer" }, "source_label": { "type": "string" }, "subgroups": { "items": { "$ref": "#/components/schemas/MeasurementResolutionSubgroup" }, "type": [ "array", "null" ] } }, "required": [ "id", "kind", "authored_form", "occurrences", "ingredients", "recipes", "candidate_unit_ids", "choices", "subgroups", "examples" ], "type": "object" }, "MeasurementResolutionGroupDetail": { "additionalProperties": true, "properties": { "group": { "$ref": "#/components/schemas/MeasurementResolutionGroup" }, "occurrences": { "items": { "$ref": "#/components/schemas/MeasurementResolutionOccurrence" }, "type": [ "array", "null" ] } }, "required": [ "group", "occurrences" ], "type": "object" }, "MeasurementResolutionInterpretationInput": { "additionalProperties": false, "properties": { "convention": { "enum": [ "us", "au", "imperial", "metric" ], "type": "string" }, "kind": { "enum": [ "canonical-unit", "convention", "keep-written" ], "type": "string" }, "unit_id": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "MeasurementResolutionOccurrence": { "additionalProperties": true, "properties": { "authored_form": { "type": "string" }, "candidate_unit_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "fingerprint": { "type": "string" }, "group_id": { "type": "string" }, "id": { "type": "string" }, "ingredient_id": { "type": "string" }, "item_id": { "type": "string" }, "recipe_id": { "type": "string" }, "recipe_title": { "type": "string" }, "resolution_key": { "type": "string" }, "source_text": { "type": "string" } }, "required": [ "id", "group_id", "item_id", "recipe_id", "recipe_title", "ingredient_id", "source_text", "authored_form", "candidate_unit_ids", "resolution_key", "fingerprint" ], "type": "object" }, "MeasurementResolutionPlanApplyInput": { "additionalProperties": false, "properties": { "expected_preview_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_preview_revision" ], "type": "object" }, "MeasurementResolutionPlanInput": { "additionalProperties": false, "properties": { "excluded_item_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "excluded_occurrence_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "expected_preview_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "interpretation": { "$ref": "#/components/schemas/MeasurementResolutionInterpretationInput" }, "resolution_group_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "interpretation", "expected_preview_revision" ], "type": "object" }, "MeasurementResolutionPlanResponse": { "additionalProperties": true, "properties": { "affected_ingredients": { "format": "int64", "minimum": 0, "type": "integer" }, "affected_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "affected_recipes": { "format": "int64", "minimum": 0, "type": "integer" }, "current_actionable_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "examples": { "items": { "$ref": "#/components/schemas/MeasurementResolutionExample" }, "type": [ "array", "null" ] }, "impact_digest": { "type": "string" }, "occurrences": { "items": { "$ref": "#/components/schemas/MeasurementResolutionOccurrence" }, "type": [ "array", "null" ] }, "pending_occurrences": { "items": { "$ref": "#/components/schemas/MeasurementResolutionOccurrence" }, "type": [ "array", "null" ] }, "plan_id": { "type": "string" }, "preview": { "$ref": "#/components/schemas/ImportPreviewResponse" }, "preview_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "remaining_actionable_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "resulting_actionable_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "unchanged_occurrences": { "format": "int64", "minimum": 0, "type": "integer" }, "unresolvable_occurrences": { "items": { "$ref": "#/components/schemas/MeasurementResolutionOccurrence" }, "type": [ "array", "null" ] }, "validation_failures": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "plan_id", "preview_revision", "impact_digest", "affected_occurrences", "affected_ingredients", "affected_recipes", "remaining_actionable_occurrences", "unchanged_occurrences", "current_actionable_occurrences", "resulting_actionable_occurrences", "validation_failures", "unresolvable_occurrences", "pending_occurrences", "examples", "occurrences" ], "type": "object" }, "MeasurementResolutionProfile": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "selects": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "unanswered": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "unit_registry_version": { "type": "string" } }, "required": [ "id", "label", "selects", "unanswered", "unit_registry_version" ], "type": "object" }, "MeasurementResolutionSubgroup": { "additionalProperties": true, "properties": { "occurrences": { "format": "int64", "minimum": 1, "type": "integer" }, "recipes": { "format": "int64", "minimum": 1, "type": "integer" }, "source_text": { "type": "string" } }, "required": [ "source_text", "occurrences", "recipes" ], "type": "object" }, "Member": { "additionalProperties": true, "properties": { "display_name": { "type": "string" }, "role": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "user_id", "display_name", "role" ], "type": "object" }, "MembersResponse": { "additionalProperties": true, "properties": { "members": { "items": { "$ref": "#/components/schemas/Member" }, "type": [ "array", "null" ] } }, "required": [ "members" ], "type": "object" }, "MergeTaxonomyInputBody": { "additionalProperties": false, "properties": { "target_id": { "type": "string" } }, "required": [ "target_id" ], "type": "object" }, "MicrowaveChoice": { "additionalProperties": false, "properties": { "duration": { "$ref": "#/components/schemas/DurationExpression" }, "power": { "$ref": "#/components/schemas/MicrowavePower" }, "rated_output_watts": { "format": "int64", "maximum": 1000000, "minimum": 1, "type": "integer" }, "source_text": { "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "duration", "source_text" ], "type": "object" }, "MicrowaveConditions": { "additionalProperties": false, "properties": { "choices": { "items": { "$ref": "#/components/schemas/MicrowaveChoice" }, "maxItems": 100, "type": [ "array", "null" ] }, "mode_text": { "maxLength": 1000, "type": "string" }, "power": { "$ref": "#/components/schemas/MicrowavePower" }, "rated_output_watts": { "format": "int64", "maximum": 1000000, "minimum": 1, "type": "integer" }, "restrictions": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "source_text": { "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "source_text" ], "type": "object" }, "MicrowavePower": { "additionalProperties": false, "properties": { "percent": { "pattern": "^(?:100|[1-9][0-9]?)$", "type": "string" }, "text": { "maxLength": 1000, "type": "string" }, "watts": { "format": "int64", "maximum": 1000000, "minimum": 1, "type": "integer" } }, "type": "object" }, "Normalization": { "additionalProperties": false, "properties": { "method": { "enum": [ "authored", "extracted", "inferred", "unresolved" ], "type": "string" }, "review": { "enum": [ "confirmed", "corrected" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "method" ], "type": "object" }, "Nutrient": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Amount", "description": "An authored zero is a value; an unmentioned nutrient is absent" }, "label": { "description": "The source's own name; required for other", "maxLength": 1000, "type": "string" }, "nutrient": { "enum": [ "energy", "fat", "saturated_fat", "trans_fat", "unsaturated_fat", "cholesterol", "carbohydrate", "sugars", "fiber", "protein", "sodium", "salt", "other" ], "type": "string" }, "source_text": { "maxLength": 1000, "type": "string" }, "text": { "description": "Wording that is not a precise value; excludes amount and unit", "maxLength": 1000, "type": "string" }, "unit": { "description": "Absent when the source stated no unit", "enum": [ "kcal", "kJ", "g", "mg", "mcg" ], "type": "string" } }, "required": [ "nutrient" ], "type": "object" }, "NutritionBasis": { "additionalProperties": false, "properties": { "kind": { "description": "recipe: the whole recipe as written; serving: one serving; quantity: a stated amount such as 100 g; unspecified: the source did not say", "enum": [ "recipe", "serving", "quantity", "unspecified" ], "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity", "description": "Serving size or reference amount; required for a quantity basis and absent for an unspecified one" }, "text": { "description": "Authored basis wording such as 1 slice", "maxLength": 1000, "type": "string" } }, "required": [ "kind" ], "type": "object" }, "NutritionStatement": { "additionalProperties": false, "properties": { "basis": { "$ref": "#/components/schemas/NutritionBasis" }, "note": { "description": "Authored qualification of the whole statement", "maxLength": 1000000, "type": "string" }, "nutrients": { "items": { "$ref": "#/components/schemas/Nutrient" }, "maxItems": 200, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "basis", "nutrients" ], "type": "object" }, "OrganizationInput": { "additionalProperties": false, "properties": { "book_membership": { "description": "Book membership changes applied in the same transaction", "items": { "$ref": "#/components/schemas/BookMembershipInput" }, "maxItems": 100, "type": [ "array", "null" ] }, "facet_ids": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "sources": { "items": { "$ref": "#/components/schemas/RecipeSource" }, "maxItems": 100, "type": [ "array", "null" ] }, "tag_ids": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "user_state": { "$ref": "#/components/schemas/UserState" } }, "required": [ "facet_ids", "tag_ids", "user_state", "sources" ], "type": "object" }, "PantryEntryInput": { "additionalProperties": false, "properties": { "amount": { "maxLength": 100, "type": "string" }, "location": { "maxLength": 100, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "note": { "maxLength": 2000, "type": "string" }, "semantic_id": { "maxLength": 200, "type": "string" }, "unit": { "maxLength": 100, "type": "string" } }, "required": [ "name" ], "type": "object" }, "ParseIngredientLineInputBody": { "additionalProperties": false, "properties": { "convention": { "description": "An explicit author choice for every applicable unqualified measure of this submitted ingredient line. It outranks source-locale lookup and preserves explicit unit definitions. Omit it when unspecified", "enum": [ "metric", "us", "au", "imperial" ], "type": "string" }, "language": { "description": "BCP 47 tag of the language the line is written in. Its primary language selects unit words and reading order; its region does not establish a measuring convention", "maxLength": 35, "type": "string" }, "source_locale": { "description": "BCP 47 tag of the locale the recipe declares. It takes the place of language when the two are sent", "maxLength": 35, "type": "string" }, "text": { "description": "One ingredient line as a person writes it, such as 2 cups flour, sifted or 小麦粉 200g", "maxLength": 10000, "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "ParseIngredientLineOutputBody": { "additionalProperties": true, "properties": { "ingredient": { "$ref": "#/components/schemas/Ingredient", "description": "The line read as an ingredient. Its normalization method is extracted when an amount was read and unresolved when the line named a measure that could not be identified safely. A line with no amount is returned as a name" } }, "required": [ "ingredient" ], "type": "object" }, "Passkey": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "id", "name", "created_at", "last_used_at" ], "type": "object" }, "PasskeyListResponse": { "additionalProperties": true, "properties": { "available": { "description": "Whether the current origin can register or use a passkey", "type": "boolean" }, "passkeys": { "items": { "$ref": "#/components/schemas/Passkey" }, "type": [ "array", "null" ] } }, "required": [ "passkeys", "available" ], "type": "object" }, "PasswordRequest": { "additionalProperties": false, "properties": { "current_password": { "type": "string", "writeOnly": true }, "new_password": { "type": "string", "writeOnly": true } }, "required": [ "current_password", "new_password" ], "type": "object" }, "PersonalToken": { "additionalProperties": true, "properties": { "created_at": { "format": "int64", "type": "integer" }, "expires_at": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "last_used_at": { "format": "int64", "type": "integer" }, "libraries": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "revoked_at": { "format": "int64", "type": "integer" }, "scopes": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "id", "name", "created_at", "expires_at", "last_used_at", "revoked_at", "scopes", "libraries" ], "type": "object" }, "PreferenceValues": { "additionalProperties": false, "properties": { "appearance": { "enum": [ "", "system", "light", "dark" ], "type": "string" }, "content_languages": { "items": { "type": "string" }, "maxItems": 20, "type": [ "array", "null" ] }, "measurement": { "enum": [ "", "original", "metric", "us", "au" ], "type": "string" }, "microwave_output_watts": { "format": "int64", "maximum": 5000, "minimum": 0, "type": "integer" }, "print_image": { "enum": [ "", "automatic", "include", "omit" ], "type": "string" }, "print_page_size": { "enum": [ "", "automatic", "letter", "a4" ], "type": "string" }, "recipe_view": { "enum": [ "", "comfortable", "compact" ], "type": "string" }, "reduced_motion": { "enum": [ "", "system", "reduce" ], "type": "string" }, "temperature": { "enum": [ "", "original", "celsius", "fahrenheit" ], "type": "string" }, "timezone": { "maxLength": 100, "type": "string" }, "ui_locale": { "maxLength": 100, "type": "string" } }, "type": "object" }, "PreferencesInputBody": { "additionalProperties": false, "properties": { "overrides": { "$ref": "#/components/schemas/PreferenceValues" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "revision", "overrides" ], "type": "object" }, "PrintDimensions": { "additionalProperties": true, "properties": { "height": { "$ref": "#/components/schemas/PrintLength" }, "width": { "$ref": "#/components/schemas/PrintLength" } }, "required": [ "width", "height" ], "type": "object" }, "PrintDocumentInfo": { "additionalProperties": true, "properties": { "bytes": { "format": "int64", "minimum": 0, "type": "integer" }, "filename": { "description": "Suggested filename for a download", "type": "string" }, "format": { "$ref": "#/components/schemas/PrintFormat" }, "id": { "description": "Signature of the renderer, effective title, source identity and revision, authorization scope, recipe revisions, preferences, and print options", "type": "string" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "recipes": { "description": "Exactly which version of each recipe was printed", "items": { "$ref": "#/components/schemas/PrintedRecipe" }, "type": [ "array", "null" ] }, "title": { "type": "string" }, "url": { "description": "Where to read the generated PDF", "type": "string" }, "warnings": { "description": "What degraded without invalidating the document, such as a photograph this library no longer holds", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "id", "url", "filename", "pages", "bytes", "title", "format", "recipes" ], "type": "object" }, "PrintFormat": { "additionalProperties": true, "properties": { "card": { "$ref": "#/components/schemas/PrintDimensions", "description": "Exact card size when cards are arranged on sheets" }, "family": { "type": "string" }, "height": { "$ref": "#/components/schemas/PrintLength" }, "size": { "type": "string" }, "width": { "$ref": "#/components/schemas/PrintLength" } }, "required": [ "size", "family", "width", "height" ], "type": "object" }, "PrintLength": { "additionalProperties": true, "properties": { "unit": { "enum": [ "in", "mm", "pt" ], "type": "string" }, "value": { "format": "double", "type": "number" } }, "required": [ "value", "unit" ], "type": "object" }, "PrintOptions": { "additionalProperties": false, "properties": { "claims": { "description": "Print the dietary and allergen statements the recipe's source makes", "type": "boolean" }, "custom_scale": { "description": "Exact batch factor, required when scale is custom", "pattern": "^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "description": { "description": "Print the recipe's headnote", "type": "boolean" }, "image": { "description": "Whether the recipe photograph is printed", "enum": [ "automatic", "include", "omit" ], "type": "string" }, "layout": { "description": "Full-page composition", "enum": [ "automatic", "side-by-side", "stacked" ], "type": "string" }, "locale": { "description": "Language tag the document is presented in", "maxLength": 35, "type": "string" }, "measurement": { "description": "Measures the recipe is written in for this print", "enum": [ "original", "metric", "us", "au" ], "type": "string" }, "microwave_output_watts": { "description": "Explicit cooking-output basis for an adjusted print; omitted prints authored timings", "format": "int64", "maximum": 5000, "minimum": 100, "type": "integer" }, "notes": { "description": "Print the recipe's notes", "type": "boolean" }, "nutrition": { "description": "Print the nutrition the recipe's source states; off by default", "type": "boolean" }, "output": { "description": "Whether cards become pages of their own size or are arranged on sheets for trimming", "enum": [ "native", "sheet-letter", "sheet-a4" ], "type": "string" }, "scale": { "description": "Which batch to print", "enum": [ "original", "preferred", "custom" ], "type": "string" }, "size": { "description": "Physical output size", "enum": [ "letter", "a4", "card-3x5", "card-4x6", "card-5x8" ], "type": "string" }, "source": { "description": "Print where the recipe came from", "type": "boolean" } }, "type": "object" }, "PrintRequestBody": { "additionalProperties": false, "properties": { "book": { "description": "Book to print instead of a recipe selection", "type": "string" }, "options": { "$ref": "#/components/schemas/PrintOptions" }, "recipes": { "description": "Library entries to print, in the order they should appear. Capabilities report the most one document holds.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "PrintedRecipe": { "additionalProperties": true, "properties": { "entry_id": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "title": { "type": "string" } }, "required": [ "entry_id", "revision", "title" ], "type": "object" }, "ProviderDependenciesResponse": { "additionalProperties": true, "properties": { "users": { "items": { "$ref": "#/components/schemas/User" }, "type": [ "array", "null" ] } }, "required": [ "users" ], "type": "object" }, "Quantity": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "kind": { "enum": [ "simple", "sum", "alternatives", "opaque" ], "type": "string" }, "options": { "items": { "$ref": "#/components/schemas/AlternativeOption" }, "maxItems": 100, "type": [ "array", "null" ] }, "terms": { "items": { "$ref": "#/components/schemas/SimpleQuantity" }, "maxItems": 100, "type": [ "array", "null" ] }, "text": { "maxLength": 1000, "type": "string" }, "unit": { "maxLength": 255, "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "RecipeAuthorCandidate": { "additionalProperties": true, "properties": { "match": { "description": "Best available tier: exact normalized name, Latin accent variant, or one edit or adjacent transposition", "enum": [ "exact", "accent", "fuzzy" ], "type": "string" }, "name": { "description": "Original author name to quote in an author: qualifier", "type": "string" }, "recipe_count": { "description": "Active recipes with this exact credited spelling in the selected library", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "name", "recipe_count", "match" ], "type": "object" }, "RecipeDependency": { "additionalProperties": false, "properties": { "recipe_id": { "description": "The other recipe's portable document ID, not a library entry ID", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "title": { "description": "The other recipe's title as authored", "maxLength": 1000, "type": "string" }, "url": { "description": "Where the other recipe is published", "format": "uri", "maxLength": 10000, "type": "string" } }, "type": "object" }, "RecipeDocument": { "additionalProperties": false, "properties": { "allergen_declarations": { "description": "Allergen presence, precaution, and absence the source stated; an unmentioned substance is unknown", "items": { "$ref": "#/components/schemas/AllergenDeclaration" }, "maxItems": 1000, "type": [ "array", "null" ] }, "assets": { "items": { "$ref": "#/components/schemas/Asset" }, "maxItems": 10000, "type": [ "array", "null" ] }, "authors": { "items": { "$ref": "#/components/schemas/Author" }, "maxItems": 100, "type": [ "array", "null" ] }, "categories": { "description": "Ordered source-authored broad classifications", "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "cooking_methods": { "description": "Ordered source-authored cooking-method labels", "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "courses": { "description": "Ordered source-authored meal-role classifications", "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "cuisines": { "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "description": { "maxLength": 1000000, "type": "string" }, "dietary_claims": { "description": "Dietary suitability the source stated; never derived from ingredients", "items": { "$ref": "#/components/schemas/DietaryClaim" }, "maxItems": 1000, "type": [ "array", "null" ] }, "equipment": { "description": "Ordered equipment the recipe identifies as required or expected; recipe content, not kitchen inventory", "items": { "$ref": "#/components/schemas/Equipment" }, "maxItems": 1000, "type": [ "array", "null" ] }, "extensions_raw": { "additionalProperties": {}, "type": "object" }, "id": { "description": "Portable recipe document identifier", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "image_refs": { "items": { "type": "string" }, "maxItems": 10000, "type": [ "array", "null" ] }, "ingredient_sections": { "items": { "$ref": "#/components/schemas/IngredientSection" }, "maxItems": 1000, "type": [ "array", "null" ] }, "instruction_sections": { "items": { "$ref": "#/components/schemas/InstructionSection" }, "maxItems": 1000, "type": [ "array", "null" ] }, "keywords": { "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "language": { "maxLength": 255, "type": "string" }, "modified": { "description": "Authored recipe or source-work modification date or date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}(?:[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?(?:[Zz]|[+-][0-9]{2}:[0-9]{2}))?$", "type": "string" }, "notes": { "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] }, "nutrition": { "description": "Authored nutrition statements, each with its own basis. Savorum does not calculate nutrition", "items": { "$ref": "#/components/schemas/NutritionStatement" }, "maxItems": 100, "type": [ "array", "null" ] }, "primary_image": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "published": { "description": "Authored recipe or source-work publication date or date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}(?:[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?(?:[Zz]|[+-][0-9]{2}:[0-9]{2}))?$", "type": "string" }, "schema_version": { "format": "int64", "maximum": 1, "minimum": 1, "type": "integer" }, "source": { "$ref": "#/components/schemas/Source" }, "source_locale": { "maxLength": 255, "type": "string" }, "sref_opaque_raw": { "additionalProperties": {}, "readOnly": true, "type": "object" }, "times": { "$ref": "#/components/schemas/Times" }, "title": { "maxLength": 1000, "minLength": 1, "type": "string" }, "translations": { "description": "Declared relationships to other renditions of this recipe in other languages. Each rendition is its own recipe; a relationship shares no content", "items": { "$ref": "#/components/schemas/Translation" }, "maxItems": 1000, "type": [ "array", "null" ] }, "variants": { "description": "Authored alternate realizations of this recipe, in source order. Preserved content, not a machine-applicable delta: identify one as a variant and show what it says rather than trying to apply it", "items": { "$ref": "#/components/schemas/Variant" }, "maxItems": 1000, "type": [ "array", "null" ] }, "yields": { "description": "Independent authored yield assertions in source order. None is primary; which one a reader scales by is their own state", "items": { "$ref": "#/components/schemas/Yield" }, "maxItems": 100, "type": [ "array", "null" ] } }, "required": [ "schema_version", "id", "title", "ingredient_sections", "instruction_sections" ], "type": "object" }, "RecipeOrganization": { "additionalProperties": true, "properties": { "facet_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "library_entry_id": { "description": "Identifier of the organized entry in the local Savorum library", "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "sources": { "items": { "$ref": "#/components/schemas/RecipeSource" }, "type": [ "array", "null" ] }, "tag_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "updated_at": { "format": "date-time", "type": "string" }, "user_state": { "$ref": "#/components/schemas/UserState" } }, "required": [ "library_entry_id", "revision", "facet_ids", "tag_ids", "user_state", "sources", "updated_at" ], "type": "object" }, "RecipeReference": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "title": { "type": "string" } }, "required": [ "id", "title", "revision" ], "type": "object" }, "RecipeRevision": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "cause": { "enum": [ "api", "manual_edit", "import", "restore", "trash" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "library_entry_id": { "description": "Identifier of the owning entry in the local Savorum library", "type": "string" }, "recipe": { "$ref": "#/components/schemas/RecipeDocument" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "source_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "state": { "enum": [ "active", "trash" ], "type": "string" } }, "required": [ "library_entry_id", "revision", "recipe", "state", "cause", "created_at" ], "type": "object" }, "RecipeRevisionSummary": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "cause": { "enum": [ "api", "manual_edit", "import", "restore", "trash" ], "type": "string" }, "changes": { "items": { "enum": [ "title", "description", "yield", "times", "ingredients", "instructions", "notes", "variants", "equipment", "photos", "source", "labels", "language", "translations", "other" ], "type": "string" }, "type": [ "array", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "library_entry_id": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "source_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "state": { "enum": [ "active", "trash" ], "type": "string" } }, "required": [ "library_entry_id", "revision", "state", "cause", "created_at" ], "type": "object" }, "RecipeSource": { "additionalProperties": false, "properties": { "accessed_at": { "format": "date-time", "type": "string" }, "attribution": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "url", "publication", "other" ], "type": "string" }, "original_title": { "type": "string" }, "page_end": { "format": "int64", "minimum": 0, "type": "integer" }, "page_start": { "format": "int64", "minimum": 0, "type": "integer" }, "publication_book_id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "RecipeSummary": { "additionalProperties": true, "properties": { "active_time": { "description": "Derived time this recipe needs the cook", "type": "string" }, "authors": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "books": { "description": "Books this recipe was deliberately placed in", "items": { "$ref": "#/components/schemas/LibraryBookSummary" }, "type": [ "array", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "favorite": { "type": "boolean" }, "id": { "description": "Identifier of this entry in the local Savorum library", "type": "string" }, "language": { "description": "The recipe's primary language as a BCP 47 tag", "type": "string" }, "last_cooked": { "description": "Most recent cooking record", "format": "date", "type": "string" }, "primary_image": { "$ref": "#/components/schemas/AssetReference" }, "recipe_id": { "description": "Portable recipe document identifier", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "source_books": { "description": "Publication books this recipe was taken from", "items": { "$ref": "#/components/schemas/LibraryBookSummary" }, "type": [ "array", "null" ] }, "tags": { "items": { "$ref": "#/components/schemas/TagSummary" }, "type": [ "array", "null" ] }, "times_cooked": { "description": "Imported baseline plus this reader's cooking records", "format": "int64", "minimum": 0, "type": "integer" }, "title": { "type": "string" }, "total_time": { "description": "Derived time from starting to being able to eat", "type": "string" }, "translations": { "description": "Other renditions of a result grouped by translation; present only when grouping was requested", "items": { "$ref": "#/components/schemas/SummaryRendition" }, "type": [ "array", "null" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "recipe_id", "title", "authors", "revision", "created_at", "updated_at", "tags", "books", "source_books", "favorite", "times_cooked" ], "type": "object" }, "RecipeTranslations": { "additionalProperties": true, "properties": { "original": { "description": "Library entry the renditions declare as their original, when they agree on one", "type": "string" }, "renditions": { "description": "Other recipes in this library that are renditions of this one", "items": { "$ref": "#/components/schemas/TranslationRendition" }, "type": [ "array", "null" ] }, "unresolved": { "description": "This recipe's own declarations that name no recipe in this library", "items": { "$ref": "#/components/schemas/Translation" }, "type": [ "array", "null" ] } }, "required": [ "renditions", "unresolved" ], "type": "object" }, "RecoverLibraryRequest": { "additionalProperties": false, "properties": { "user_id": { "type": "string" } }, "required": [ "user_id" ], "type": "object" }, "RecoveryCodesResponse": { "additionalProperties": true, "properties": { "codes": { "description": "Shown once; only their hashes are stored", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "codes" ], "type": "object" }, "RecoveryStatusResponse": { "additionalProperties": true, "properties": { "allowed": { "description": "Whether provider policy allows recovery codes for this account", "type": "boolean" }, "remaining": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "remaining", "allowed" ], "type": "object" }, "RemovedResponse": { "additionalProperties": true, "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "type": "object" }, "RevokedResponse": { "additionalProperties": true, "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "type": "object" }, "SavedMeal": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "dishes": { "items": { "$ref": "#/components/schemas/MealDish" }, "maxItems": 50, "minItems": 1, "type": [ "array", "null" ] }, "id": { "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "notes": { "maxLength": 10000, "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "dishes", "revision", "created_at", "updated_at" ], "type": "object" }, "SavedMealInput": { "additionalProperties": false, "properties": { "dishes": { "items": { "$ref": "#/components/schemas/MealDish" }, "maxItems": 50, "minItems": 1, "type": [ "array", "null" ] }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "notes": { "maxLength": 10000, "type": "string" } }, "required": [ "name", "dishes" ], "type": "object" }, "SavedMealSummary": { "additionalProperties": true, "properties": { "dish_count": { "format": "int64", "type": "integer" }, "dish_names": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "id", "revision", "name", "dish_names", "dish_count" ], "type": "object" }, "SavedMealsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/SavedMeal" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "SavedView": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "query": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "sort": { "enum": [ "relevance", "updated-desc", "title-asc", "rating-desc" ], "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "query", "revision", "created_at", "updated_at" ], "type": "object" }, "SavedViewInput": { "additionalProperties": false, "properties": { "query": { "maxLength": 200, "type": "string" }, "sort": { "enum": [ "relevance", "updated-desc", "title-asc", "rating-desc" ], "maxLength": 100, "type": "string" }, "title": { "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "title", "query" ], "type": "object" }, "SavedViewsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/SavedView" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "SelectLibraryRequest": { "additionalProperties": false, "properties": { "library_id": { "type": "string" } }, "required": [ "library_id" ], "type": "object" }, "SessionsResponse": { "additionalProperties": true, "properties": { "sessions": { "items": { "$ref": "#/components/schemas/AccountSession" }, "type": [ "array", "null" ] } }, "required": [ "sessions" ], "type": "object" }, "SetMemberRequest": { "additionalProperties": false, "properties": { "role": { "enum": [ "viewer", "editor", "owner" ], "type": "string" } }, "required": [ "role" ], "type": "object" }, "ShoppingActivity": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "int64", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/ShoppingActivityItem" }, "type": [ "array", "null" ] }, "kind": { "enum": [ "add", "edit", "bought", "reopened", "remove", "restore", "move", "merge", "split", "review", "create-list", "rename-list" ], "type": "string" } }, "required": [ "id", "created_at", "actor_id", "actor_name", "kind", "items" ], "type": "object" }, "ShoppingActivityItem": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ShoppingActivityOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/ShoppingActivity" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "ShoppingApplyInput": { "additionalProperties": false, "properties": { "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "input": { "$ref": "#/components/schemas/ShoppingReviewInput" }, "selections": { "items": { "$ref": "#/components/schemas/ShoppingSelection" }, "maxItems": 2000, "type": [ "array", "null" ] }, "token": { "type": "string" } }, "required": [ "id", "input", "token", "selections" ], "type": "object" }, "ShoppingChange": { "additionalProperties": false, "properties": { "after_item_id": { "maxLength": 100, "type": "string" }, "base_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "bought": { "type": "boolean" }, "buy": { "maxLength": 200, "type": "string" }, "category": { "maxLength": 100, "type": "string" }, "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "item_id": { "maxLength": 100, "minLength": 1, "type": "string" }, "kind": { "enum": [ "add", "edit", "remove", "restore", "move", "merge", "split" ], "type": "string" }, "merge_item_ids": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "name": { "maxLength": 200, "type": "string" }, "note": { "maxLength": 2000, "type": "string" }, "source_ids": { "items": { "type": "string" }, "maxItems": 200, "type": [ "array", "null" ] } }, "required": [ "id", "kind", "item_id", "base_revision" ], "type": "object" }, "ShoppingChoice": { "additionalProperties": true, "properties": { "amount": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "quantity": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "id", "name", "note", "quantity" ], "type": "object" }, "ShoppingItem": { "additionalProperties": true, "properties": { "arranged": { "type": "boolean" }, "bought": { "type": "boolean" }, "buy": { "type": "string" }, "category": { "type": "string" }, "deleted": { "type": "boolean" }, "fields": { "additionalProperties": { "format": "int64", "minimum": 0, "type": "integer" }, "type": "object" }, "id": { "type": "string" }, "merged_into": { "type": "string" }, "name": { "type": "string" }, "needed": { "type": "string" }, "note": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "sources": { "items": { "$ref": "#/components/schemas/ShoppingSource" }, "type": [ "array", "null" ] } }, "required": [ "id", "name", "buy", "needed", "note", "category", "bought", "deleted", "revision", "fields", "sources" ], "type": "object" }, "ShoppingList": { "additionalProperties": true, "properties": { "applied_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "id": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ShoppingItem" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "requirements": { "additionalProperties": { "$ref": "#/components/schemas/ShoppingRequirement" }, "type": "object" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "selections": { "additionalProperties": { "$ref": "#/components/schemas/ShoppingSelection" }, "type": "object" } }, "required": [ "id", "name", "revision", "items", "selections", "requirements" ], "type": "object" }, "ShoppingListInput": { "additionalProperties": false, "properties": { "id": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ShoppingListRename": { "additionalProperties": false, "properties": { "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ShoppingListSummary": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ShoppingPortion": { "additionalProperties": false, "properties": { "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "recipe_id": { "maxLength": 100, "minLength": 1, "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "scale": { "maxLength": 100, "type": "string" } }, "required": [ "id", "recipe_id" ], "type": "object" }, "ShoppingRequirement": { "additionalProperties": true, "properties": { "choice_id": { "type": "string" }, "choices": { "items": { "$ref": "#/components/schemas/ShoppingChoice" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "previous_name": { "type": "string" }, "previous_quantity": { "type": "string" }, "reviewed_at": { "format": "date-time", "readOnly": true, "type": "string" }, "selected": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/ShoppingSource" } }, "required": [ "id", "source", "choices", "selected", "choice_id" ], "type": "object" }, "ShoppingReview": { "additionalProperties": true, "properties": { "outdated": { "type": "boolean" }, "removed": { "items": { "$ref": "#/components/schemas/ShoppingSource" }, "type": [ "array", "null" ] }, "requirements": { "items": { "$ref": "#/components/schemas/ShoppingRequirement" }, "type": [ "array", "null" ] }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "token": { "type": "string" } }, "required": [ "revision", "token", "requirements", "removed" ], "type": "object" }, "ShoppingReviewInput": { "additionalProperties": false, "properties": { "again": { "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]*$", "type": "string" }, "meal_ids": { "items": { "type": "string" }, "maxItems": 50, "type": [ "array", "null" ] }, "portions": { "items": { "$ref": "#/components/schemas/ShoppingPortion" }, "maxItems": 50, "type": [ "array", "null" ] }, "refresh_recipes": { "type": "boolean" } }, "type": "object" }, "ShoppingSelection": { "additionalProperties": false, "properties": { "choice_id": { "type": "string" }, "id": { "type": "string" }, "selected": { "type": "boolean" } }, "required": [ "id", "selected", "choice_id" ], "type": "object" }, "ShoppingSource": { "additionalProperties": true, "properties": { "again": { "type": "string" }, "amount": { "type": "string" }, "dish_id": { "type": "string" }, "id": { "type": "string" }, "ingredient_id": { "type": "string" }, "label": { "type": "string" }, "meal_date": { "format": "date", "type": "string" }, "meal_id": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "quantity": { "type": "string" }, "recipe_id": { "type": "string" }, "recipe_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "unit": { "type": "string" } }, "required": [ "id", "label", "name", "quantity" ], "type": "object" }, "SignInMethod": { "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "provider", "name", "enabled" ], "type": "object" }, "SignInMethodsResponse": { "additionalProperties": true, "properties": { "methods": { "items": { "$ref": "#/components/schemas/SignInMethod" }, "type": [ "array", "null" ] } }, "required": [ "methods" ], "type": "object" }, "SimpleQuantity": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "kind": { "enum": [ "simple" ], "type": "string" }, "unit": { "maxLength": 255, "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$", "type": "string" } }, "required": [ "kind", "amount" ], "type": "object" }, "Source": { "additionalProperties": false, "properties": { "application": { "description": "Portable source application or format identity; namespaces source_id", "maxLength": 1000, "type": "string" }, "attribution": { "description": "Portable source credit or attribution", "maxLength": 1000000, "type": "string" }, "name": { "description": "Portable source name credited by the recipe", "maxLength": 1000, "type": "string" }, "retrieved_at": { "description": "Supplementary retrieval time; does not identify a source", "format": "date-time", "type": "string" }, "source_id": { "description": "Identifier within application; never a Savorum library or publication ID", "maxLength": 1000, "type": "string" }, "url": { "description": "Portable canonical source URL", "format": "uri", "maxLength": 10000, "type": "string" } }, "type": "object" }, "SourceRefreshConflictWire": { "additionalProperties": true, "properties": { "area": { "type": "string" }, "base": { "type": "string" }, "local": { "type": "string" }, "path": { "type": "string" }, "remote": { "type": "string" } }, "required": [ "path", "area" ], "type": "object" }, "SourceRefreshPreviewWire": { "additionalProperties": true, "properties": { "base": { "$ref": "#/components/schemas/RecipeDocument" }, "base_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "conflicts": { "items": { "$ref": "#/components/schemas/SourceRefreshConflictWire" }, "type": [ "array", "null" ] }, "entry_id": { "type": "string" }, "expected_revision": { "format": "int64", "minimum": 0, "type": "integer" }, "id": { "type": "string" }, "local": { "$ref": "#/components/schemas/RecipeDocument" }, "merged": { "$ref": "#/components/schemas/RecipeDocument" }, "remote": { "$ref": "#/components/schemas/RecipeDocument" }, "summary": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "id", "entry_id", "expected_revision", "base_revision", "base", "local", "remote", "merged", "conflicts", "summary" ], "type": "object" }, "SourceRefreshURLInputBody": { "additionalProperties": false, "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url", "expected_revision" ], "type": "object" }, "Step": { "additionalProperties": false, "properties": { "id": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "image_refs": { "items": { "type": "string" }, "maxItems": 10000, "type": [ "array", "null" ] }, "ingredient_uses": { "items": { "$ref": "#/components/schemas/IngredientUse" }, "maxItems": 10000, "type": [ "array", "null" ] }, "temperatures": { "items": { "$ref": "#/components/schemas/Temperature" }, "maxItems": 100, "type": [ "array", "null" ] }, "text": { "description": "Instruction prose; a step requires a title or text", "maxLength": 1000000, "type": "string" }, "timing_refs": { "description": "Canonical timing assertions this step is associated with", "items": { "type": "string" }, "maxItems": 50, "type": [ "array", "null" ] }, "title": { "description": "Optional authored heading for this instruction", "maxLength": 1000, "type": "string" } }, "required": [ "id" ], "type": "object" }, "Subscription": { "additionalProperties": true, "properties": { "consecutive_failures": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "enabled": { "type": "boolean" }, "event_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "library_id": { "type": "string" }, "name": { "type": "string" }, "pause_reason": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "secret_rotated_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" }, "url": { "type": "string" } }, "required": [ "updated_at", "updated_by", "id", "name", "url", "event_types", "enabled", "revision", "created_at", "secret_rotated_at", "consecutive_failures" ], "type": "object" }, "SuggestionPageBookSelectionSummary": { "additionalProperties": true, "properties": { "has_more": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/BookSelectionSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" } }, "required": [ "items", "has_more", "limit", "offset" ], "type": "object" }, "SuggestionPageRecipeSummary": { "additionalProperties": true, "properties": { "has_more": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/RecipeSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" } }, "required": [ "items", "has_more", "limit", "offset" ], "type": "object" }, "SuggestionPageSavedMealSummary": { "additionalProperties": true, "properties": { "has_more": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SavedMealSummary" }, "type": [ "array", "null" ] }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" } }, "required": [ "items", "has_more", "limit", "offset" ], "type": "object" }, "SummaryRendition": { "additionalProperties": true, "properties": { "id": { "description": "Library entry identifier", "type": "string" }, "language": { "description": "The rendition's primary language as a BCP 47 tag", "type": "string" }, "matched": { "description": "The rendition also matched the search; false when the request had no search", "type": "boolean" }, "title": { "type": "string" } }, "required": [ "id", "title", "language", "matched" ], "type": "object" }, "Tag": { "additionalProperties": true, "properties": { "color": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "revision", "created_at", "updated_at" ], "type": "object" }, "TagInput": { "additionalProperties": false, "properties": { "color": { "pattern": "^#[A-Fa-f0-9]{6}$", "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "TagSummary": { "additionalProperties": true, "properties": { "color": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "TagsOutputBody": { "additionalProperties": true, "properties": { "items": { "items": { "$ref": "#/components/schemas/Tag" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "Target": { "additionalProperties": false, "properties": { "id": { "maxLength": 255, "minLength": 1, "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "id", "revision" ], "type": "object" }, "Temperature": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/TemperatureAmount" }, "note": { "maxLength": 1000, "type": "string" }, "purpose": { "$ref": "#/components/schemas/TemperaturePurpose" }, "source_text": { "maxLength": 1000, "type": "string" }, "text": { "maxLength": 1000, "type": "string" }, "unit": { "maxLength": 255, "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$", "type": "string" } }, "type": "object" }, "TemperatureAmount": { "additionalProperties": false, "properties": { "approximate": { "type": "boolean" }, "max": { "maxLength": 128, "pattern": "^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "min": { "maxLength": 128, "pattern": "^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "value": { "maxLength": 128, "pattern": "^-?(0|[1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" } }, "type": "object" }, "TemperaturePurpose": { "additionalProperties": false, "properties": { "kind": { "enum": [ "oven", "internal", "oil", "water", "surface", "other" ], "type": "string" }, "label": { "maxLength": 1000, "type": "string" } }, "required": [ "kind" ], "type": "object" }, "TimeSummary": { "additionalProperties": true, "properties": { "active": { "$ref": "#/components/schemas/DurationExpression", "description": "Time the recipe needs the cook" }, "cook": { "$ref": "#/components/schemas/DurationExpression" }, "elapsed": { "$ref": "#/components/schemas/DurationExpression", "description": "Time from starting to being able to eat" }, "prep": { "$ref": "#/components/schemas/DurationExpression" }, "written_total": { "$ref": "#/components/schemas/DurationExpression", "description": "An authored total the recipe itself contradicts, preserved but not presented as the elapsed time" } }, "type": "object" }, "Times": { "additionalProperties": false, "properties": { "additional": { "$ref": "#/components/schemas/DurationExpression" }, "assertions": { "items": { "$ref": "#/components/schemas/TimingAssertion" }, "maxItems": 50, "type": [ "array", "null" ] }, "cook": { "$ref": "#/components/schemas/DurationExpression" }, "prep": { "$ref": "#/components/schemas/DurationExpression" }, "total": { "$ref": "#/components/schemas/DurationExpression" } }, "type": "object" }, "TimingAssertion": { "additionalProperties": false, "properties": { "attention": { "description": "Authored semantics; absent means the recipe does not say", "enum": [ "active", "passive" ], "type": "string" }, "duration": { "$ref": "#/components/schemas/DurationExpression" }, "id": { "maxLength": 255, "type": "string" }, "kind": { "description": "Absent when the source supports a duration but no defensible classification", "enum": [ "prep", "soak", "brine", "marinate", "cure", "proof", "ferment", "chill", "freeze", "drain", "cook", "rest", "cool", "other" ], "type": "string" }, "label": { "description": "Required when kind is other; may retitle a named one", "maxLength": 100, "type": "string" }, "microwave": { "$ref": "#/components/schemas/MicrowaveConditions" }, "note": { "maxLength": 1000, "type": "string" }, "provenance": { "description": "How Savorum came to hold this timing; not part of the portable recipe", "enum": [ "derived", "supplemental" ], "type": "string" } }, "required": [ "id", "duration" ], "type": "object" }, "TokenGrant": { "additionalProperties": true, "properties": { "created_at": { "format": "int64", "type": "integer" }, "expires_at": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "last_used_at": { "format": "int64", "type": "integer" }, "libraries": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "revoked_at": { "format": "int64", "type": "integer" }, "scopes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "secret": { "type": "string" } }, "required": [ "secret", "id", "name", "created_at", "expires_at", "last_used_at", "revoked_at", "scopes", "libraries" ], "type": "object" }, "TokenListResponse": { "additionalProperties": true, "properties": { "policy": { "$ref": "#/components/schemas/TokenPolicy" }, "tokens": { "items": { "$ref": "#/components/schemas/PersonalToken" }, "type": [ "array", "null" ] } }, "required": [ "tokens", "policy" ], "type": "object" }, "TokenPolicy": { "additionalProperties": true, "properties": { "allow_nonexpiring": { "type": "boolean" }, "default_days": { "format": "int64", "type": "integer" }, "maximum_days": { "format": "int64", "type": "integer" } }, "required": [ "default_days", "maximum_days", "allow_nonexpiring" ], "type": "object" }, "TokenRequest": { "additionalProperties": false, "properties": { "days": { "format": "int64", "type": "integer" }, "libraries": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "nonexpiring": { "type": "boolean" }, "scopes": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "name", "days", "nonexpiring", "scopes", "libraries" ], "type": "object" }, "Translation": { "additionalProperties": false, "properties": { "language": { "description": "The counterpart's primary language as a BCP 47 tag", "maxLength": 255, "minLength": 2, "type": "string" }, "recipe_id": { "description": "The counterpart's portable recipe document ID, not a library entry ID", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "relation": { "description": "original: this recipe was translated from the counterpart; translation: the counterpart was translated from this recipe; alternate: the same recipe in another language with no stated direction", "enum": [ "original", "translation", "alternate" ], "type": "string" }, "title": { "description": "The counterpart's title as authored", "maxLength": 1000, "type": "string" }, "url": { "description": "Where the counterpart is published", "format": "uri", "maxLength": 10000, "type": "string" } }, "required": [ "relation", "language" ], "type": "object" }, "TranslationRendition": { "additionalProperties": true, "properties": { "id": { "description": "Library entry identifier", "type": "string" }, "language": { "description": "BCP 47 tag of the rendition's primary language", "type": "string" }, "linked": { "description": "One of the two recipes names the other, so the relationship can be removed from either", "type": "boolean" }, "relation": { "description": "How the rendition relates to the requested recipe", "enum": [ "original", "translation", "alternate" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title", "language", "relation", "linked" ], "type": "object" }, "UpdateUserRequest": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "password": { "type": "string", "writeOnly": true } }, "type": "object" }, "User": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "display_name": { "type": "string" }, "instance_admin": { "type": "boolean" }, "status": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "status", "created_at", "user_id", "display_name", "instance_admin" ], "type": "object" }, "UserPreferences": { "additionalProperties": true, "properties": { "effective": { "$ref": "#/components/schemas/PreferenceValues" }, "interface_locales": { "description": "Interface languages this server ships. A preview locale is incomplete or unreviewed and is used only when chosen explicitly", "items": { "$ref": "#/components/schemas/InterfaceLocale" }, "type": [ "array", "null" ] }, "overrides": { "$ref": "#/components/schemas/PreferenceValues" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "version", "revision", "overrides", "effective", "interface_locales" ], "type": "object" }, "UserState": { "additionalProperties": false, "properties": { "favorite": { "type": "boolean" }, "personal_note": { "maxLength": 1000000, "type": "string" }, "preferred_scale": { "description": "Preferred batch as an exact factor, for a yield that is not a number", "maxLength": 128, "pattern": "^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "preferred_yield": { "description": "Preferred yield as an exact amount of the recipe's own yield", "maxLength": 128, "pattern": "^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$", "type": "string" }, "preferred_yield_assertion": { "description": "Position in the recipe's yields of the yield this reader shows first and scales by. It does not reorder the recipe's yields.", "format": "int64", "maximum": 99, "minimum": 0, "type": "integer" }, "rating": { "format": "int32", "maximum": 5, "minimum": 1, "type": "integer" } }, "required": [ "favorite" ], "type": "object" }, "UsersResponse": { "additionalProperties": true, "properties": { "users": { "items": { "$ref": "#/components/schemas/ManagedUser" }, "type": [ "array", "null" ] } }, "required": [ "users" ], "type": "object" }, "Variant": { "additionalProperties": false, "properties": { "id": { "description": "Recipe-local identifier that claims use to scope themselves to this variant", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "text": { "maxLength": 1000000, "minLength": 1, "type": "string" }, "title": { "maxLength": 1000, "type": "string" } }, "required": [ "text" ], "type": "object" }, "Yield": { "additionalProperties": false, "properties": { "label": { "maxLength": 1000, "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "text": { "maxLength": 1000, "type": "string" } }, "type": "object" } }, "securitySchemes": { "bearerToken": { "description": "A personal API token. An instance in local mode accepts requests without it.", "scheme": "bearer", "type": "http" }, "browserSession": { "description": "A browser session; hosted instances use `__Host-savorum_session`, declared by their running OpenAPI document. Writes also send the session's `X-CSRF-Token` header. An instance in local mode accepts requests without it.", "in": "cookie", "name": "savorum_session", "type": "apiKey" } } }, "info": { "description": "The /api/v1 namespace is the compatibility boundary for browser, native, and external clients. Optional response fields and new operations may be added. Removing or renaming fields, changing meaning, tightening accepted inputs, or changing behavior through defaults requires a new API major. Clients must ignore unknown response fields.\n\n### Credentials and local mode\n\nAn instance started without `--auth-enabled` runs in local mode: it authenticates nobody and acts as one persisted local user, so keep it on loopback or behind an access-controlled network or proxy.\n\nWith authentication enabled, a browser session or a personal API token is required. Send a token as `Authorization: Bearer \u003ctoken\u003e`, and name a library with `X-Savorum-Library: \u003clibrary-id\u003e` when the token reaches more than one. A token's authority is the intersection of its scopes, its optional library restriction, and the current membership of the account that owns it.\n\nA request using any method other than `GET`, `HEAD`, or `OPTIONS` passes an origin check first. A cookie-authenticated one additionally requires the session-bound `X-CSRF-Token` header. Bearer requests set no cookie and need no CSRF header.\n\nThe `bearerToken` and `browserSession` security schemes name these credentials. Operations that answer without credentials declare that explicitly.\n\n### Extension boundary\n\nExternal integrations use the authenticated HTTP API, versioned events, signed webhooks, SREF, and iCalendar. Internal import, export, authentication, and extraction adapters are compiled, typed components over canonical models and services. They receive no database handle. Adapter metadata is registered by the capability implementation, not a frontend list. There is no Go native plugin, shared-library loader, server-script runtime, plugin SQL migration, or plugin package manager. Any future richer extension protocol must be out of process with explicit capabilities and API authorization.\n\n### Conventions\n\nOperation IDs are `verb-resource`. Responses that carry a revision use a strong `ETag`, and a conditional write echoes it in `If-Match`. Meals and saved meals differ: their `ETag` validates the representation as returned, and `If-Match` takes their `revision` field as a strong ETag. Problem responses use `application/problem+json` with stable machine-readable codes, field locations, and revision context. Missing write preconditions return 428, stale revisions return 412. Shopping field-edit conflicts retain their documented 409 outcome and explicit resolution flow.", "license": { "identifier": "AGPL-3.0-only", "name": "AGPL-3.0-only" }, "title": "Savorum API", "version": "1" }, "openapi": "3.1.0", "paths": { "/api/v1/account": { "delete": { "description": "Requires explicit confirmation. Shared libraries survive. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "delete-current-account", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Delete the current account", "tags": [ "Account" ] }, "get": { "description": "Includes the libraries this account can reach. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "get-current-account", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountState" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "security": [ {}, { "bearerToken": [] }, { "browserSession": [] } ], "summary": "Get the current account", "tags": [ "Account" ] } }, "/api/v1/account/audit": { "get": { "description": "Instance history for an administrator, or owned-library history for a library owner. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-audit-events", "parameters": [ { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "library", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "actor", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "target", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "since", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "until", "schema": { "type": "string" } }, { "description": "Optional filter; times are Unix seconds and before is an exclusive event ID cursor. Results contain at most 100 events, newest first.", "in": "query", "name": "before", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List audit events", "tags": [ "Account" ] } }, "/api/v1/account/group-mappings": { "get": { "description": "Instance administration. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "list-provider-group-mappings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMappingsResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "List group mappings", "tags": [ "Authentication" ] }, "post": { "description": "Maps one provider group value to a library role. Instance administration. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "set-provider-group-mapping", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMapping" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMapping" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Set a group mapping", "tags": [ "Authentication" ] } }, "/api/v1/account/group-mappings/{id}": { "delete": { "description": "Immediately removes the grants that rule produced. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "remove-provider-group-mapping", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Remove a group mapping", "tags": [ "Authentication" ] } }, "/api/v1/account/invitations/accept": { "post": { "description": "Grants only the invited library role, never instance administration. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "accept-library-invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAcceptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Accept an invitation", "tags": [ "Invitations" ] } }, "/api/v1/account/invitations/register": { "post": { "description": "Creates the account and consumes the invitation in one transaction. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "register-invited-local-account", "parameters": [ { "description": "Must be the configured public origin.", "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationRegisterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." } }, "security": [], "summary": "Register from an invitation", "tags": [ "Invitations" ] } }, "/api/v1/account/invitations/{id}": { "delete": { "description": "A revoked link cannot be reused. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "revoke-library-invitation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Revoke an invitation", "tags": [ "Invitations" ] } }, "/api/v1/account/library": { "post": { "description": "Chooses which accessible library this browser acts in. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "select-current-library", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectLibraryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Select a library", "tags": [ "Account" ] } }, "/api/v1/account/login": { "post": { "description": "Authenticates a local account and rotates the browser session. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "login-account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "security": [], "summary": "Sign in", "tags": [ "Sessions" ] } }, "/api/v1/account/logout": { "post": { "description": "Revokes the current browser session. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "logout-account", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Sign out", "tags": [ "Sessions" ] } }, "/api/v1/account/methods": { "get": { "description": "The methods attached to the current account. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "list-sign-in-methods", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethodsResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "List sign-in methods", "tags": [ "Sign-in methods" ] } }, "/api/v1/account/methods/{id}": { "delete": { "description": "Refused when it would leave no usable sign-in or recovery method. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "unlink-sign-in-method", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Unlink a sign-in method", "tags": [ "Sign-in methods" ] } }, "/api/v1/account/passkeys": { "get": { "description": "Includes whether the current origin can register or use one. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "list-passkeys", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyListResponse" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "List passkeys", "tags": [ "Passkeys" ] } }, "/api/v1/account/passkeys/login/begin": { "post": { "description": "Usernameless: the authenticator supplies the account. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "begin-passkey-login", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "publicKey": { "additionalProperties": true, "description": "WebAuthn PublicKeyCredentialCreationOptions or PublicKeyCredentialRequestOptions, as the browser API takes them.", "type": "object" } }, "required": [ "publicKey" ], "type": "object" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "security": [], "summary": "Begin passkey sign-in", "tags": [ "Passkeys" ] } }, "/api/v1/account/passkeys/login/finish": { "post": { "description": "Verifies the assertion and rotates the browser session. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "finish-passkey-login", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialLoginResponse" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "security": [], "summary": "Finish passkey sign-in", "tags": [ "Passkeys" ] } }, "/api/v1/account/passkeys/register/begin": { "post": { "description": "Requests a discoverable, user-verified credential. Requires recent authentication. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "begin-passkey-registration", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "publicKey": { "additionalProperties": true, "description": "WebAuthn PublicKeyCredentialCreationOptions or PublicKeyCredentialRequestOptions, as the browser API takes them.", "type": "object" } }, "required": [ "publicKey" ], "type": "object" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Begin passkey registration", "tags": [ "Passkeys" ] } }, "/api/v1/account/passkeys/register/finish": { "post": { "description": "Verifies the creation response and stores only public material. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "finish-passkey-registration", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Finish passkey registration", "tags": [ "Passkeys" ] } }, "/api/v1/account/passkeys/{id}": { "delete": { "description": "Refused when it would leave no usable sign-in or recovery method. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "revoke-passkey", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Revoke a passkey", "tags": [ "Passkeys" ] }, "put": { "description": "Requires recent authentication. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "rename-passkey", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Rename a passkey", "tags": [ "Passkeys" ] } }, "/api/v1/account/password": { "put": { "description": "Requires the current password. Revokes every session of the account, including the one that made the request, so the client signs in again. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "change-account-password", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Change the password", "tags": [ "Account" ] } }, "/api/v1/account/providers/{id}/dependencies": { "get": { "description": "The users whose sign-in depends on a provider. Check before disabling one. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "list-provider-dependent-users", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderDependenciesResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "List provider dependencies", "tags": [ "Sign-in methods" ] } }, "/api/v1/account/recovery": { "get": { "description": "Reports the unused code count and the provider recovery policy. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "get-recovery-status", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryStatusResponse" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Get recovery status", "tags": [ "Recovery codes" ] }, "post": { "description": "Replaces any existing set and shows ten codes exactly once. Requires recent authentication. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "generate-recovery-codes", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodesResponse" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "summary": "Generate recovery codes", "tags": [ "Recovery codes" ] } }, "/api/v1/account/recovery/login": { "post": { "description": "Consumes one code and establishes a recovery-marked session. Browser session authentication and CSRF apply to protected mutations. Recent authentication means a session created within five minutes. WebAuthn challenges are one-use, browser-bound and expire after five minutes. Public sign-in requires the configured Origin header. Responses must not be cached.", "operationId": "login-recovery-code", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "type": "string", "writeOnly": true }, "login": { "type": "string" } }, "required": [ "login", "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialLoginResponse" } } }, "description": "Completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Authentication, policy, rate, or protocol validation failure." } }, "security": [], "summary": "Sign in with a recovery code", "tags": [ "Recovery codes" ] } }, "/api/v1/account/sessions": { "delete": { "description": "Keeps the session making the request. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "revoke-other-account-sessions", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Revoke other sessions", "tags": [ "Sessions" ] }, "get": { "description": "Active browser sessions owned by this account. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-account-sessions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List sessions", "tags": [ "Sessions" ] } }, "/api/v1/account/sessions/{id}": { "delete": { "description": "The session must belong to the current account. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "revoke-account-session", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Revoke a session", "tags": [ "Sessions" ] } }, "/api/v1/account/tokens": { "get": { "description": "Returns safe metadata and the instance token policy, never a token secret. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-account-tokens", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenListResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List API tokens", "tags": [ "API tokens" ] }, "post": { "description": "The secret appears once in this response and cannot be retrieved again. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "create-account-token", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenGrant" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Create an API token", "tags": [ "API tokens" ] } }, "/api/v1/account/tokens/{id}": { "delete": { "description": "Takes effect immediately; the token is not reissued. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "revoke-account-token", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Revoke an API token", "tags": [ "API tokens" ] } }, "/api/v1/assets": { "post": { "operationId": "create-asset", "parameters": [ { "description": "Declared media type; verified against the bytes", "in": "header", "name": "X-Asset-Media-Type", "required": true, "schema": { "description": "Declared media type; verified against the bytes", "type": "string" } }, { "description": "Optional expected lowercase SHA-256 digest", "in": "header", "name": "X-Asset-SHA256", "schema": { "description": "Optional expected lowercase SHA-256 digest", "pattern": "^[a-f0-9]{64}$", "type": "string" } }, { "description": "Optional expected byte count", "in": "header", "name": "X-Asset-Size", "schema": { "description": "Optional expected byte count", "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBlob" } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "507": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Insufficient Storage" } }, "summary": "Upload an asset", "tags": [ "Assets" ] } }, "/api/v1/auth/native-links": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "finish-native-provider-link", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "The one-time link code from the return target. It expires after one minute and is consumed by the first attempt with a valid session.", "type": "string", "writeOnly": true }, "code_verifier": { "description": "The PKCE verifier: 43 to 128 unreserved characters.", "type": "string", "writeOnly": true }, "redirect_uri": { "description": "The return target used to begin the link.", "type": "string" } }, "required": [ "code", "code_verifier", "redirect_uri" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrf_token": { "type": "string" }, "invitation_accepted": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token", "invitation_accepted" ], "type": "object" } } }, "description": "The provider identity is linked to the current account. Linking ends the account's sessions, so the current session is replaced by a new one, returned in the instance's session cookie." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "`invalid_grant`: the code is unknown, expired, already used, issued to another session, or does not match the verifier. Nothing is linked and the current session remains." }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "409": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "`identity_conflict`: the provider identity belongs to another account. Nothing is linked and the current session remains." }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "summary": "Finish a native link", "tags": [ "Authentication" ] } }, "/api/v1/auth/native-sessions": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "finish-native-provider-login", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "The one-time code from the return target. It expires after one minute and is consumed by the first attempt.", "type": "string", "writeOnly": true }, "code_verifier": { "description": "The PKCE verifier: 43 to 128 unreserved characters.", "type": "string", "writeOnly": true }, "redirect_uri": { "description": "The return target used to begin the sign-in.", "type": "string" } }, "required": [ "code", "code_verifier", "redirect_uri" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrf_token": { "type": "string" }, "invitation_accepted": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token", "invitation_accepted" ], "type": "object" } } }, "description": "The one-time code and its PKCE verifier are exchanged for an ordinary session, returned in the instance's session cookie. A presented earlier session is revoked." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "summary": "Finish a native sign-in", "tags": [ "Authentication" ] } }, "/api/v1/auth/providers": { "get": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "list-authentication-providers", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "providers": { "items": { "properties": { "display_name": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "oidc", "saml", "ldap", "proxy", "managed" ], "type": "string" } }, "required": [ "id", "kind", "display_name" ], "type": "object" }, "type": "array" } }, "required": [ "providers" ], "type": "object" } } }, "description": "The configured providers, ordered by ID." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [], "summary": "List sign-in providers", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/acs": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "complete-saml-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "RelayState": { "type": "string" }, "SAMLResponse": { "type": "string", "writeOnly": true } }, "required": [ "RelayState", "SAMLResponse" ], "type": "object" } } }, "required": true }, "responses": { "303": { "description": "Successful sign-in creates an ordinary secure session and opens account settings, or the library home for a managed provider. A sign-in or link started at the native entry instead redirects to its return target with `code` and `state`, or with `error` (`access_denied` or `authentication_failed`) and `state`, and sets no browser session. A link code changes nothing until `finish-native-provider-link` confirms it." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [], "summary": "Complete a SAML sign-in", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/callback": { "get": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "complete-oidc-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Successful sign-in creates an ordinary secure session and opens account settings, or the library home for a managed provider. A sign-in or link started at the native entry instead redirects to its return target with `code` and `state`, or with `error` (`access_denied` or `authentication_failed`) and `state`, and sets no browser session. A link code changes nothing until `finish-native-provider-link` confirms it." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [], "summary": "Complete browser sign-in", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/login": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "begin-provider-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } }, { "description": "Required when explicitly linking to the current account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "invitation_token": { "type": "string", "writeOnly": true }, "link": { "description": "Requires a current browser session and CSRF proof; callback rechecks that session.", "type": "boolean" }, "login": { "type": "string" }, "password": { "type": "string", "writeOnly": true } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "authorization_url": { "description": "Where to send the browser to continue with an OIDC, SAML or managed provider.", "format": "uri", "type": "string" } }, "required": [ "authorization_url" ], "type": "object" }, { "properties": { "csrf_token": { "type": "string" }, "invitation_accepted": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token", "invitation_accepted" ], "type": "object" } ] } } }, "description": "OIDC, SAML and managed providers return the authorization_url to navigate to. LDAP and trusted-proxy providers sign in directly and return the new session." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [ {}, { "browserSession": [] } ], "summary": "Begin a provider sign-in", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/managed-sessions": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "finish-managed-native-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code_verifier": { "type": "string", "writeOnly": true }, "grant": { "type": "string", "writeOnly": true } }, "required": [ "grant", "code_verifier" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrf_token": { "type": "string" }, "invitation_accepted": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/AccountUser" } }, "required": [ "user", "csrf_token", "invitation_accepted" ], "type": "object" } } }, "description": "An ordinary local session after one-use grant, PKCE and local membership checks." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "summary": "Redeem a managed session grant", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/metadata": { "get": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "get-saml-metadata", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/samlmetadata+xml": { "schema": { "type": "string" } } }, "description": "SP metadata; entity ID and exact ACS URL." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [], "summary": "Get SAML metadata", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/native": { "get": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "begin-native-provider-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "description": "An exactly permitted return target: `savorum://auth/callback`.", "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "description": "16 to 256 unreserved characters, returned unchanged to the app.", "in": "query", "name": "state", "required": true, "schema": { "type": "string" } }, { "description": "Base64url SHA-256 of the app's code verifier, without padding.", "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": true, "schema": { "enum": [ "S256" ], "type": "string" } }, { "description": "A ticket from `create-native-link-ticket`. The return then carries a link code for `finish-native-provider-link` instead of a sign-in code.", "in": "query", "name": "link_ticket", "schema": { "type": "string" } } ], "responses": { "303": { "description": "Sets the browser-bound transaction cookie and redirects to the OIDC, SAML or managed provider. Open this URL in the app's authentication browser, not with a native HTTP client." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "summary": "Begin a native sign-in", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/native-link-tickets": { "post": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "create-native-link-ticket", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code_challenge": { "description": "Base64url SHA-256 of the app's code verifier, without padding. The native entry must present the same challenge.", "type": "string" }, "code_challenge_method": { "enum": [ "S256" ], "type": "string" } }, "required": [ "code_challenge", "code_challenge_method" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "link_ticket": { "type": "string" } }, "required": [ "link_ticket" ], "type": "object" } } }, "description": "A one-minute, single-use ticket bound to the current session and the PKCE challenge. Pass it as `link_ticket` to `begin-native-provider-login` with the same challenge." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "summary": "Start a native link", "tags": [ "Authentication" ] } }, "/api/v1/auth/{provider}/start": { "get": { "description": "Available only when account authentication is enabled. Provider configuration is restart-bound. Local logout does not require an external provider. Responses must not be cached.", "operationId": "begin-managed-browser-login", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Starts a browser-bound managed sign-in. The hosting service confirms its account before the instance replaces the browser session." }, "400": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "401": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "403": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "429": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" }, "500": { "content": { "application/problem+json": { "schema": { "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" } } }, "description": "Structured authentication boundary failure" } }, "security": [], "summary": "Open a managed library", "tags": [ "Authentication" ] } }, "/api/v1/books": { "get": { "operationId": "list-books", "parameters": [ { "description": "Maximum number of books to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "description": "Maximum number of books to return", "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of books to skip", "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "description": "Number of books to skip", "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Report whether each book contains this library recipe entry", "explode": false, "in": "query", "name": "entry_id", "schema": { "description": "Report whether each book contains this library recipe entry", "type": "string" } }, { "description": "Book lifecycle state to list", "explode": false, "in": "query", "name": "state", "schema": { "default": "active", "description": "Book lifecycle state to list", "enum": [ "active", "trash" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BooksOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List books", "tags": [ "Books" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-book", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a book", "tags": [ "Books" ] } }, "/api/v1/books/lookup": { "post": { "operationId": "get-books-summaries", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupOutputBookSelectionSummaryBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Resolve books selections", "tags": [ "Books" ] } }, "/api/v1/books/suggestions": { "get": { "operationId": "list-books-suggestions", "parameters": [ { "explode": false, "in": "query", "name": "q", "schema": { "maxLength": 200, "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 10, "format": "int64", "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionPageBookSelectionSummary" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Suggest books", "tags": [ "Books" ] } }, "/api/v1/books/{book_id}/assets/{id}": { "get": { "operationId": "get-book-asset", "parameters": [ { "in": "path", "name": "book_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } } ], "responses": { "200": { "content": { "*/*": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The stored bytes. A conservative raster image is served inline with its own media type; any other type is an application/octet-stream attachment." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a book asset", "tags": [ "Assets" ] }, "head": { "operationId": "head-book-asset", "parameters": [ { "in": "path", "name": "book_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } }, "Content-Security-Policy": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Cross-Origin-Resource-Policy": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Head a book asset", "tags": [ "Assets" ] } }, "/api/v1/books/{book_id}/assets/{id}/derivatives/{preset}": { "get": { "operationId": "get-book-asset-derivative", "parameters": [ { "description": "Revalidate a cached image after checking current access", "in": "header", "name": "If-None-Match", "schema": { "description": "Revalidate a cached image after checking current access", "maxLength": 4096, "type": "string" } }, { "in": "path", "name": "book_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } }, { "in": "path", "name": "preset", "required": true, "schema": { "pattern": "^(card|reader|thumb)$", "type": "string" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } }, "image/png": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A resized image." }, "304": { "description": "The authorized derivative matches If-None-Match." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a book asset derivative", "tags": [ "Assets" ] } }, "/api/v1/books/{id}": { "delete": { "operationId": "trash-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Move a book to trash", "tags": [ "Books" ] }, "get": { "operationId": "get-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a book", "tags": [ "Books" ] }, "put": { "operationId": "replace-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a book", "tags": [ "Books" ] } }, "/api/v1/books/{id}/export/sref-bundle": { "get": { "description": "Writes the recipes a book holds, in the book's own order, as a `.srefbundle`. It exports the recipes rather than the book: SREF has no portable collection model, so the book's identity, chapters, and membership notes remain here rather than travelling as identifiers that mean nothing elsewhere. The server owns the ordering, so a client does not have to read a book in order to send it back.", "operationId": "export-book-sref-bundle", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A `.sref` bundle." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Export a book bundle", "tags": [ "Export" ] }, "head": { "description": "An export is generated on demand, so there is no response to describe without producing it. Use GET instead.", "operationId": "head-export-book-sref-bundle", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "405": { "description": "Method Not Allowed", "headers": { "Allow": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Head a book bundle export", "tags": [ "Export" ] } }, "/api/v1/books/{id}/restore": { "post": { "operationId": "restore-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Restore a book from trash", "tags": [ "Books" ] } }, "/api/v1/books/{id}/revisions": { "get": { "operationId": "list-book-revisions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookRevisionsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List book revisions", "tags": [ "Books" ] } }, "/api/v1/books/{id}/revisions/{revision}": { "get": { "operationId": "get-book-revision", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookRevision" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a book revision", "tags": [ "Books" ] } }, "/api/v1/books/{id}/revisions/{revision}/restore": { "post": { "operationId": "restore-book-revision", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Restore a book revision", "tags": [ "Books" ] } }, "/api/v1/books/{id}/sourced-recipes": { "get": { "operationId": "list-book-sourced-recipes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookSourceRecipesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List sourced recipes", "tags": [ "Books" ] } }, "/api/v1/bulk/recipes/book": { "post": { "description": "Partial success: each item uses normal resource authorization and its own revision. Tags/book use the organization's revision; trash/restore use the recipe revision. Book membership also requires the initial book revision, advanced only by this batch's successful items. Work above the advertised synchronous limit, or with an Idempotency-Key, returns 202 with a persistent job. No arbitrary operation names are accepted.", "operationId": "apply-bulk-book-recipes", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply-bulk-book-recipesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "Persistent job accepted; poll the returned Location", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Bulk book recipes", "tags": [ "Bulk" ] } }, "/api/v1/bulk/recipes/read": { "post": { "description": "Partial success: each item uses normal resource authorization and its own revision. Tags/book use the organization's revision; trash/restore use the recipe revision. Book membership also requires the initial book revision, advanced only by this batch's successful items. Work above the advertised synchronous limit, or with an Idempotency-Key, returns 202 with a persistent job. No arbitrary operation names are accepted.", "operationId": "apply-bulk-read-recipes", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply-bulk-read-recipesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "Persistent job accepted; poll the returned Location", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Bulk read recipes", "tags": [ "Bulk" ] } }, "/api/v1/bulk/recipes/restore": { "post": { "description": "Partial success: each item uses normal resource authorization and its own revision. Tags/book use the organization's revision; trash/restore use the recipe revision. Book membership also requires the initial book revision, advanced only by this batch's successful items. Work above the advertised synchronous limit, or with an Idempotency-Key, returns 202 with a persistent job. No arbitrary operation names are accepted.", "operationId": "apply-bulk-restore-recipes", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply-bulk-restore-recipesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "Persistent job accepted; poll the returned Location", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Bulk restore recipes", "tags": [ "Bulk" ] } }, "/api/v1/bulk/recipes/tags": { "post": { "description": "Partial success: each item uses normal resource authorization and its own revision. Tags/book use the organization's revision; trash/restore use the recipe revision. Book membership also requires the initial book revision, advanced only by this batch's successful items. Work above the advertised synchronous limit, or with an Idempotency-Key, returns 202 with a persistent job. No arbitrary operation names are accepted.", "operationId": "apply-bulk-tags-recipes", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply-bulk-tags-recipesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "Persistent job accepted; poll the returned Location", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Bulk tags recipes", "tags": [ "Bulk" ] } }, "/api/v1/bulk/recipes/trash": { "post": { "description": "Partial success: each item uses normal resource authorization and its own revision. Tags/book use the organization's revision; trash/restore use the recipe revision. Book membership also requires the initial book revision, advanced only by this batch's successful items. Work above the advertised synchronous limit, or with an Idempotency-Key, returns 202 with a persistent job. No arbitrary operation names are accepted.", "operationId": "apply-bulk-trash-recipes", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply-bulk-trash-recipesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOutputBody" } } }, "description": "Persistent job accepted; poll the returned Location", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Bulk trash recipes", "tags": [ "Bulk" ] } }, "/api/v1/calendar-feeds": { "get": { "description": "Lists the feeds the reader created for the selected library. A library owner sees every feed publishing the library's plan so they can revoke any of them. Feed URLs are never listed.", "operationId": "list-calendar-feeds", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarFeedsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List calendar feeds", "tags": [ "Plan" ] }, "post": { "description": "Creates a read-only feed of the selected library's plan. The response is the only time its URL is shown: anyone holding the URL can read the plan until the feed is rotated or revoked. The feed keeps working only while its creator can read the plan. Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-calendar-feed", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarFeedInputBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarFeedSecret" } } }, "description": "Created" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a calendar feed", "tags": [ "Plan" ] } }, "/api/v1/calendar-feeds/{id}": { "delete": { "operationId": "delete-calendar-feed", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 100, "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Revoke a calendar feed", "tags": [ "Plan" ] } }, "/api/v1/calendar-feeds/{id}/rotate": { "post": { "description": "Issues a new URL; the previous one stops working immediately. Calendars subscribed to the old URL must subscribe again.", "operationId": "rotate-calendar-feed", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 100, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarFeedSecret" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a calendar feed's URL", "tags": [ "Plan" ] } }, "/api/v1/capabilities": { "get": { "description": "Unauthenticated requests return product, API compatibility, interactive sign-in methods, and sign-in features only. `auth.native_sign_in` means a native app can complete OIDC, SAML, and managed sign-in through `begin-native-provider-login` and `finish-native-provider-login`. `auth.native_link` means a signed-in native app can link an OIDC or SAML identity through `create-native-link-ticket`, `begin-native-provider-login`, and `finish-native-provider-link`. `auth.managed_session` means a managed provider is configured and its web and native sign-in use short-lived, tenant-audienced grants after PKCE code redemption. `auth.managed_native_session` means a native client can redeem a scoped hosting grant through `finish-managed-native-login` for an ordinary local session. Authenticated requests add registered formats, optional features, and enforced bounds. `recipes.search.ingredient` means ingredient: queries match indexed ingredient names, including optional and alternative names, with original-line fallback only when the name is absent. All words in one qualifier must match the same ingredient. Capabilities describe availability, not a grant of authorization. Schema version 1 permits additive optional fields and new IDs; clients ignore unknown IDs. Cache for the current session and refresh after reconnect or configuration changes.", "operationId": "get-capabilities", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "The credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "security": [ {}, { "bearerToken": [] }, { "browserSession": [] } ], "summary": "Discover capabilities", "tags": [ "Instance" ] } }, "/api/v1/configuration": { "get": { "operationId": "get-instance-configuration", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfiguration" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Get instance configuration", "tags": [ "Instance" ] } }, "/api/v1/events": { "get": { "description": "Authorized server-sent events use the versioned domain envelope. Send Last-Event-ID (or after) to resume up to seven days of retained history. A resync event requires a normal API refresh; cursor events advance past irrelevant facts. Authorization is rechecked every second. There are at most four streams per account, 1024 per instance, 100 events per page, 15-second heartbeats, and five-minute connections. Reconnect with backoff; correctness never depends on this connection. Tokens are accepted only in Authorization, never query parameters.", "operationId": "get-library-events", "parameters": [ { "in": "header", "name": "Last-Event-Id", "schema": { "maxLength": 100, "type": "string" } }, { "explode": false, "in": "query", "name": "after", "schema": { "maxLength": 100, "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "Bounded, resumable event stream" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Follow library changes", "tags": [ "Events" ] } }, "/api/v1/export-jobs": { "post": { "description": "Uses the ordinary export service, with bounded background compression and an authenticated 24-hour artifact. Idempotency-Key retains the same job for 24 hours; reusing a key with different input returns 409.", "operationId": "create-export-job", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "Accepted", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Queue an export", "tags": [ "Jobs" ] } }, "/api/v1/exports/sref-bundle": { "head": { "description": "An export is generated on demand, so there is no response to describe without producing it. Use POST instead.", "operationId": "head-export-recipes-sref-bundle", "responses": { "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "405": { "description": "Method Not Allowed", "headers": { "Allow": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Head a selection bundle export", "tags": [ "Export" ] }, "post": { "description": "Writes a `.srefbundle`: an ordered ZIP container of complete `.sref` packages. Each member is byte for byte the artifact exporting that recipe on its own would produce, so any one recipe can be taken out and used without the bundle. A bundle is not a Savorum backup; it holds portable recipes and nothing about how this library is organised.", "operationId": "export-recipes-sref-bundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBundleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A `.sref` bundle." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Export a selection bundle", "tags": [ "Export" ] } }, "/api/v1/facets": { "get": { "operationId": "list-facets", "parameters": [ { "explode": false, "in": "query", "name": "kind", "schema": { "enum": [ "course", "cuisine", "method", "dietary" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List facets", "tags": [ "Facets" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-facet", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facet" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a facet", "tags": [ "Facets" ] } }, "/api/v1/facets/{id}": { "delete": { "operationId": "delete-facet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a facet", "tags": [ "Facets" ] }, "get": { "operationId": "get-facet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facet" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a facet", "tags": [ "Facets" ] }, "put": { "operationId": "replace-facet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facet" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a facet", "tags": [ "Facets" ] } }, "/api/v1/facets/{id}/merge": { "post": { "operationId": "merge-facet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeTaxonomyInputBody" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Merge a facet", "tags": [ "Facets" ] } }, "/api/v1/health": { "get": { "operationId": "get-health", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthOutputBody" } } }, "description": "OK" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "Check health", "tags": [ "Instance" ] } }, "/api/v1/import-jobs": { "get": { "description": "Newest first. Progress is counted from the recipes themselves on every read, so it cannot drift from what actually happened.", "operationId": "list-import-jobs", "parameters": [ { "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "state", "schema": { "enum": [ "pending", "running", "completed", "completed-with-errors", "cancelled", "failed", "interrupted" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListImportJobsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List import jobs", "tags": [ "Import jobs" ] }, "post": { "description": "kind=url uses the same SSRF-protected URL importer as the UI. kind=file accepts base64 file_content; kind=text accepts text. filename is a display basename, never a local path. Default policy is preview-only; automatic commit requires require-no-warnings or allow-warnings. Read /jobs/{id}/preview for structured fidelity diagnostics and /jobs/{id} for state. Idempotency-Key is retained atomically for 24 hours.", "operationId": "create-import-job", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Create-import-jobRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "Accepted", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Queue an import preview", "tags": [ "Jobs" ] } }, "/api/v1/import-jobs/{job_id}": { "get": { "operationId": "get-import-job", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResource" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get an import job", "tags": [ "Import jobs" ] } }, "/api/v1/import-jobs/{job_id}/cancel": { "post": { "description": "Cancellation is cooperative and is not a rollback. Nothing further is scheduled, the batch already being written finishes safely, and every recipe already committed stays in the library.", "operationId": "cancel-import-job", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResource" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Cancel an import job", "tags": [ "Import jobs" ] } }, "/api/v1/import-jobs/{job_id}/items": { "get": { "description": "One row per recipe the import was asked to bring in, in the order they were selected. Filtering is by what a reader is looking for rather than by storage state.", "operationId": "list-import-job-items", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Review-required and informational describe consequences rather than storage states", "explode": false, "in": "query", "name": "filter", "schema": { "description": "Review-required and informational describe consequences rather than storage states", "enum": [ "imported", "skipped", "review-required", "informational", "failed", "pending", "cancelled" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListImportJobItemsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List import job items", "tags": [ "Import jobs" ] } }, "/api/v1/import-jobs/{job_id}/resume": { "post": { "description": "Runs the recipes an interrupted, cancelled, or partly failed import never finished, from what was written down for each of them. A recipe whose bytes only ever existed inside the uploaded file is reported as needing that file again rather than retried against nothing.", "operationId": "resume-import-job", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResource" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Resume an import job", "tags": [ "Import jobs" ] } }, "/api/v1/ingredient-lines/parse": { "post": { "description": "Reads one typed ingredient line into an amount, unit, name, and note using the unit words of the line's language. Nothing is stored. The result is the reading an import would make, so a line typed in the editor and the same line imported are read alike.", "operationId": "preview-ingredient-line", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseIngredientLineInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseIngredientLineOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read an ingredient line", "tags": [ "Recipes" ] } }, "/api/v1/instance-webhooks": { "get": { "description": "Library owners manage this library's subscriptions. Instance administrators manage instance security-event subscriptions through /instance-webhooks. Personal tokens cannot manage either. Destinations require HTTPS and public DNS addresses unless a deployment operator explicitly trusts a private CIDR. DNS is checked on each connection; up to three method-preserving HTTPS redirects are revalidated before following. Events contain IDs and minimal facts, never recipe bodies or credentials. Delivery is at least once. Receivers verify the exact body with HMAC-SHA256 over timestamp + '.' + body using Savorum-Signature: t=\u003cUnix seconds\u003e,v1=\u003chex\u003e, reject timestamps outside five minutes, then persistently deduplicate delivery_id. Savorum-Delivery-ID and Savorum-Event-ID also occur inside the signed body. Secrets appear once on create or rotate. Rotation immediately invalidates the old key for future attempts, including queued retries. Keep signing-key files with private instance backups. Retries cover network failures, 408, 429, and 5xx: up to eight attempts per cycle within 24 hours, exponential delay from 15 seconds with jitter, capped at one hour, honoring bounded Retry-After. Other statuses end the cycle. History retains up to 1000 finished deliveries per subscription for 30 days and 32 attempts per delivery. Repeated final failures automatically pause delivery; fix the receiver before re-enabling. Paused subscriptions retain queued work but do not subscribe to new events.", "operationId": "list-instance-webhooks", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Subscription" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List instance webhooks", "tags": [ "Webhooks" ] }, "post": { "description": "Library owners manage this library's subscriptions. Instance administrators manage instance security-event subscriptions through /instance-webhooks. Personal tokens cannot manage either. Destinations require HTTPS and public DNS addresses unless a deployment operator explicitly trusts a private CIDR. DNS is checked on each connection; up to three method-preserving HTTPS redirects are revalidated before following. Events contain IDs and minimal facts, never recipe bodies or credentials. Delivery is at least once. Receivers verify the exact body with HMAC-SHA256 over timestamp + '.' + body using Savorum-Signature: t=\u003cUnix seconds\u003e,v1=\u003chex\u003e, reject timestamps outside five minutes, then persistently deduplicate delivery_id. Savorum-Delivery-ID and Savorum-Event-ID also occur inside the signed body. Secrets appear once on create or rotate. Rotation immediately invalidates the old key for future attempts, including queued retries. Keep signing-key files with private instance backups. Retries cover network failures, 408, 429, and 5xx: up to eight attempts per cycle within 24 hours, exponential delay from 15 seconds with jitter, capped at one hour, honoring bounded Retry-After. Other statuses end the cycle. History retains up to 1000 finished deliveries per subscription for 30 days and 32 attempts per delivery. Repeated final failures automatically pause delivery; fix the receiver before re-enabling. Paused subscriptions retain queued work but do not subscribe to new events. Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-instance-webhook", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Create instance webhook", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}": { "delete": { "operationId": "delete-instance-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Delete instance webhook", "tags": [ "Webhooks" ] }, "get": { "operationId": "get-instance-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read instance webhook", "tags": [ "Webhooks" ] }, "put": { "operationId": "update-instance-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Update instance webhook", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}/deliveries": { "get": { "operationId": "list-instance-webhook-deliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "maximum": 1000, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Delivery" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List instance deliveries", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}/deliveries/{delivery_id}": { "get": { "operationId": "get-instance-webhook-delivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read instance delivery", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}/deliveries/{delivery_id}/redeliver": { "post": { "operationId": "create-instance-webhook-redelivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Create-instance-webhook-redeliveryResponse" } } }, "description": "Accepted" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Retry instance delivery", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}/rotate-secret": { "post": { "description": "The old secret is retired as soon as rotation completes. All future attempts, including retries of existing deliveries, use the new secret. Install the returned secret before re-enabling a paused subscription. The secret cannot be read later.", "operationId": "replace-instance-webhook-secret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Rotate instance key", "tags": [ "Webhooks" ] } }, "/api/v1/instance-webhooks/{id}/test": { "post": { "operationId": "create-instance-webhook-test", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } }, "description": "Accepted" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Test instance webhook", "tags": [ "Webhooks" ] } }, "/api/v1/jobs/{id}": { "get": { "description": "Creator-scoped and authorized at every read. Transfer jobs and temporary artifacts expire after 24 hours. Existing import job IDs use the same lifecycle projection here, for reads, cancel, and resume; /import-jobs keeps its detailed compatible representation. An import job has no revision: its revision is 0 and the response carries no ETag.", "operationId": "get-job", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Read a bulk or transfer job", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/cancel": { "post": { "description": "Already committed item results remain. A mutation in progress may finish before cancellation is observed.", "operationId": "cancel-job", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Cancel unfinished work", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/commit": { "post": { "description": "require-no-warnings refuses warning/error diagnostics; allow-warnings still refuses errors. Repeating commit returns the original import job. Duplicate policy is reject or skip; updates to existing recipes require the normal reviewed reconciliation flow.", "operationId": "commit-automation-import", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commit-automation-importRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Commit a frozen import", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/downloads/{handle}": { "get": { "description": "Opaque handle, creator and current library authorization required. No unauthenticated/static download URL. Expires 24 hours after job creation.", "operationId": "get-job-artifact", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "handle", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "Authenticated SREF package or bundle" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Download an export artifact", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/items": { "get": { "description": "A common per-item lifecycle. Import-specific fidelity and source details are carried in import. Bulk results appear as items finish. Use next_offset for the next page; pages stop near 16 MiB of stored snapshots (one larger recipe is still returned). interrupted uncertain mutations explicitly report outcome-unknown and are never silently repeated.", "operationId": "list-job-results", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResultsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read job item results", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/preview": { "get": { "operationId": "get-job-import-preview", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Read a frozen import preview", "tags": [ "Jobs" ] } }, "/api/v1/jobs/{id}/resume": { "post": { "description": "Send the job revision in If-Match. An import job has no revision and needs none. Completed item results remain; an in-flight mutation whose result could not be checkpointed reports outcome-unknown and is not repeated. Refetch that resource before deciding a new action. Original per-item resource revisions continue to apply.", "operationId": "resume-job", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResource" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Resume interrupted work", "tags": [ "Jobs" ] } }, "/api/v1/libraries": { "get": { "description": "Libraries reachable through membership. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-libraries", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibrariesResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List libraries", "tags": [ "Libraries" ] }, "post": { "description": "The current account becomes its owner. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "create-library", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLibraryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Library" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Create a library", "tags": [ "Libraries" ] } }, "/api/v1/libraries/{id}": { "delete": { "description": "Requires explicit confirmation and library ownership. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "delete-library", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLibraryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Delete a library", "tags": [ "Libraries" ] } }, "/api/v1/libraries/{id}/invitations": { "get": { "description": "Metadata and accepted or revoked state, never the secret. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "list-library-invitations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationListResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "List invitations", "tags": [ "Invitations" ] }, "post": { "description": "Returns the link secret once. Library ownership or instance administration required. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "create-library-invitation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreateResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Create an invitation", "tags": [ "Invitations" ] } }, "/api/v1/libraries/{id}/members": { "get": { "description": "Library ownership required. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-library-members", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List library members", "tags": [ "Library members" ] } }, "/api/v1/libraries/{id}/members/{user}": { "delete": { "description": "Removes a manual membership. Library ownership required. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "remove-library-member", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Remove a library member", "tags": [ "Library members" ] }, "put": { "description": "Assigns a manual membership role. Library ownership required. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "set-library-member", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Set a library member", "tags": [ "Library members" ] } }, "/api/v1/libraries/{id}/recover": { "post": { "description": "Assigns an owner through audited administrator recovery. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "recover-library-owner", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoverLibraryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Recover library ownership", "tags": [ "Library members" ] } }, "/api/v1/me/preferences": { "get": { "operationId": "get-current-user-preferences", "parameters": [ { "in": "header", "name": "Accept-Language", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Get preferences", "tags": [ "Account" ] }, "put": { "operationId": "replace-current-user-preferences", "parameters": [ { "in": "header", "name": "Accept-Language", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferencesInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Replace preferences", "tags": [ "Account" ] } }, "/api/v1/meals": { "get": { "operationId": "list-meals", "parameters": [ { "explode": false, "in": "query", "name": "from", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Also return meals without a date", "explode": false, "in": "query", "name": "include_unscheduled", "schema": { "default": false, "description": "Also return meals without a date", "type": "boolean" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MealsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List meals", "tags": [ "Plan" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-meal", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MealInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meal" } } }, "description": "Created", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe and shopping details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Plan a meal", "tags": [ "Plan" ] } }, "/api/v1/meals/calendar": { "get": { "description": "Writes the dated meals in a range as all-day events that any calendar application can import. An imported file is a copy: later changes to the plan reach a calendar only through a subscription feed.", "operationId": "export-meal-calendar", "parameters": [ { "description": "First day to include", "explode": false, "in": "query", "name": "from", "required": true, "schema": { "description": "First day to include", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" } }, { "description": "Last day to include, at most 366 days after the first", "explode": false, "in": "query", "name": "to", "required": true, "schema": { "description": "Last day to include, at most 366 days after the first", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "text/calendar": { "schema": { "type": "string" } } }, "description": "iCalendar document" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Download the plan as iCalendar", "tags": [ "Plan" ] } }, "/api/v1/meals/{id}": { "delete": { "operationId": "delete-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a meal", "tags": [ "Plan" ] }, "get": { "operationId": "get-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meal" } } }, "description": "OK", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe and shopping details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a meal", "tags": [ "Plan" ] }, "put": { "operationId": "replace-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MealInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meal" } } }, "description": "OK", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe and shopping details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a meal", "tags": [ "Plan" ] } }, "/api/v1/meals/{id}/copy": { "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-meal-copy", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MealPlacementInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meal" } } }, "description": "Created", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe and shopping details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Copy a meal", "tags": [ "Plan" ] } }, "/api/v1/pantry": { "get": { "description": "Library-shared hints only. Presence and approximate amounts never imply sufficient stock, change shopping selections, or travel in SREF.", "operationId": "list-pantry", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Entry" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read pantry presence", "tags": [ "Pantry" ] } }, "/api/v1/pantry/{id}": { "delete": { "operationId": "delete-pantry-entry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Remove a pantry hint", "tags": [ "Pantry" ] }, "put": { "description": "Use a stable client-generated ID. If-None-Match: * creates an entry; If-Match updates an observed revision. At most 2000 entries per library.", "operationId": "replace-pantry-entry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } }, { "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PantryEntryInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Save pantry presence", "tags": [ "Pantry" ] } }, "/api/v1/print/documents": { "post": { "description": "Freezes the revision of every named recipe, resolves the batch and measures asked for, and typesets the result. The document is generated on demand and is not stored as part of any recipe.", "operationId": "create-print-document", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintRequestBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintDocumentInfo" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Create a print document", "tags": [ "Print" ] } }, "/api/v1/print/documents/{id}": { "get": { "description": "Returns the exact bytes the preview showed when the generated document is still held for the same authorization scope. Downloading and printing read the same document rather than generating it a second time. The identifier signs the renderer, effective title, source identity and revision, authorization scope, recipe revisions, preferences, and print options, so it can only ever name these bytes.", "operationId": "get-print-document", "parameters": [ { "description": "Generated document identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Generated document identifier", "pattern": "^[a-f0-9]{64}$", "type": "string" } }, { "description": "Offer the document as a download rather than for viewing", "explode": false, "in": "query", "name": "download", "schema": { "description": "Offer the document as a download rather than for viewing", "type": "boolean" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The generated document." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a print document", "tags": [ "Print" ] }, "head": { "operationId": "head-print-document", "parameters": [ { "description": "Generated document identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Generated document identifier", "pattern": "^[a-f0-9]{64}$", "type": "string" } }, { "description": "Offer the document as a download rather than for viewing", "explode": false, "in": "query", "name": "download", "schema": { "description": "Offer the document as a download rather than for viewing", "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } }, "Content-Security-Policy": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Head a print document", "tags": [ "Print" ] } }, "/api/v1/recipe-authors": { "get": { "description": "Resolve a complete author name from active recipes in the selected library. Returns only the best available tier: Unicode case-folded NFC and whitespace equality, then Latin accent variants, then one edit or adjacent transposition for 5 to 64 rune names with at least four letters. Punctuation is literal in exact matching. Non-Latin marks are preserved; scripts are not transliterated. Names are ordered by their original Unicode spelling. Exact and accent matches have no candidate cap; typo comparisons evaluate at most 128 indexed candidate names. Choose a returned name before applying the exact author: recipe filter, and ask for a choice when suggestions are ambiguous.", "operationId": "list-recipe-authors", "parameters": [ { "description": "Complete author name to resolve; only recipe author fields are searched", "explode": false, "in": "query", "name": "q", "required": true, "schema": { "description": "Complete author name to resolve; only recipe author fields are searched", "maxLength": 200, "minLength": 1, "type": "string" } }, { "description": "Maximum number of author names to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Maximum number of author names to return", "format": "int64", "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRecipeAuthorsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Find recipe authors", "tags": [ "Recipe authors" ] } }, "/api/v1/recipe-references": { "get": { "operationId": "list-recipe-references", "parameters": [ { "description": "Library state to list", "explode": false, "in": "query", "name": "state", "schema": { "default": "active", "description": "Library state to list", "enum": [ "active", "trash" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRecipeReferencesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List recipe references", "tags": [ "Recipes" ] } }, "/api/v1/recipes": { "get": { "operationId": "list-recipes", "parameters": [ { "description": "Maximum number of entries to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "description": "Maximum number of entries to return", "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of entries to skip", "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "description": "Number of entries to skip", "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Recipe text with bounded title/author typo matching and structured filters. author: requires full author-name membership with Unicode case, NFC, and whitespace normalization; accents and punctuation are preserved. ingredient: requires literal word-prefix matches within one ingredient name, including optional and alternative names, with original-line fallback only when that name is absent", "explode": false, "in": "query", "name": "q", "schema": { "description": "Recipe text with bounded title/author typo matching and structured filters. author: requires full author-name membership with Unicode case, NFC, and whitespace normalization; accents and punctuation are preserved. ingredient: requires literal word-prefix matches within one ingredient name, including optional and alternative names, with original-line fallback only when that name is absent", "maxLength": 200, "type": "string" } }, { "description": "Library state to list", "explode": false, "in": "query", "name": "state", "schema": { "default": "active", "description": "Library state to list", "enum": [ "active", "trash" ], "type": "string" } }, { "description": "Recipe list ordering", "explode": false, "in": "query", "name": "sort", "schema": { "default": "relevance", "description": "Recipe list ordering", "enum": [ "relevance", "updated-desc", "title-asc", "rating-desc" ], "type": "string" } }, { "description": "Present each set of translated recipes once, as the rendition the preferred languages choose among those that match", "explode": false, "in": "query", "name": "group_translations", "schema": { "description": "Present each set of translated recipes once, as the rendition the preferred languages choose among those that match", "type": "boolean" } }, { "description": "Comma-separated BCP 47 content languages in order of preference, used when grouping translations", "explode": false, "in": "query", "name": "languages", "schema": { "description": "Comma-separated BCP 47 content languages in order of preference, used when grouping translations", "maxLength": 1000, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRecipesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List recipes", "tags": [ "Recipes" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-recipe", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDocument" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a recipe", "tags": [ "Recipes" ] } }, "/api/v1/recipes/import": { "post": { "description": "Reads SREF recipe documents. Every recipe is validated before any is written. A recipe already in this library is reported rather than duplicated unless on_duplicate says otherwise. A recipe with photographs travels as a `.sref` package and is uploaded to `/api/v1/recipes/import-package`.", "operationId": "import-recipes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Import SREF documents", "tags": [ "Import" ] } }, "/api/v1/recipes/import-external": { "post": { "description": "A multipart upload of exports from other applications. Every file part is read; the field names carry no meaning.", "operationId": "import-external-recipes", "parameters": [ { "description": "What to do with a recipe the library already holds.", "in": "query", "name": "on_duplicate", "schema": { "default": "skip", "enum": [ "reject", "skip", "replace" ], "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" }, "type": "object" } } }, "description": "The exports to import.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "formats": { "description": "The importers that recognized the uploads.", "items": { "type": "string" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/ImportedRecipe" }, "type": "array" } }, "required": [ "items", "formats" ], "type": "object" } } }, "description": "What was imported, and which formats were recognized." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Import third-party exports", "tags": [ "Import" ] } }, "/api/v1/recipes/import-package": { "post": { "description": "The request body is the archive itself. `on_duplicate` chooses what happens to a recipe the library already holds.", "operationId": "import-recipe-package", "parameters": [ { "description": "What to do with a recipe the library already holds.", "in": "query", "name": "on_duplicate", "schema": { "default": "reject", "enum": [ "reject", "skip", "replace" ], "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } }, "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ImportedRecipe" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "The recipes the package carried, and what became of each." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Import an SREF package", "tags": [ "Import" ] } }, "/api/v1/recipes/import-preview": { "post": { "description": "Accepts every format the exchange service understands: SREF documents, packages, bundles, saved recipe pages and third-party exports. Nothing reaches the library until the preview is committed.", "operationId": "create-import-preview", "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" }, "type": "object" } } }, "description": "The files to review before importing.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "The staged preview, its items, and when it expires." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Create an import preview", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}": { "delete": { "description": "A preview that has expired, has been committed, or was started by another caller returns 404. A client that only wants the preview gone can treat 404 as success.", "operationId": "cancel-import-preview", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The preview is gone." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Cancel an import preview", "tags": [ "Import" ] }, "get": { "description": "A review can be finished in passes. This returns the preview as it stands, so what was left after an earlier selection was imported can be taken up again.", "operationId": "get-import-preview", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "The staged preview, with the candidates already imported taken out." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Get an import preview", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/commit": { "post": { "description": "Either `item_ids` with an `on_duplicate` policy, or `resolutions` naming what to do with each item individually. A preview with items left over comes back as `remaining`.", "operationId": "commit-import-preview", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewCommitInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewCommitResponse" } } }, "description": "What was imported, and whatever the preview still holds." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Commit an import preview", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/items/{item_id}/image": { "get": { "description": "The bytes are served from the preview, not the library, and are never stored: a preview writes nothing.", "operationId": "get-import-preview-image", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "*/*": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The image, with its own media type.", "headers": { "Cache-Control": { "description": "`private, no-store`: a preview image is not the library's copy.", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "`nosniff`.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Get a preview item image", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/items/{item_id}/text": { "post": { "description": "Reparses corrected text through the common recipe importer while keeping the uploaded original available for the explicit retention choice.", "operationId": "update-import-preview-text", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewTextInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "The revised preview." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Implemented" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Update preview item text", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/jobs": { "post": { "description": "Takes the selected recipes out of the review session and imports them as durable work. The response is a job to watch rather than a result to wait for: closing the page, losing the connection, or restarting Savorum does not abandon the import. Recipes are committed in batches, so partial success is preserved and inspectable recipe by recipe.", "operationId": "start-import-job", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } }, { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobStartInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobStartResponse" } } }, "description": "Accepted", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Start an import job", "tags": [ "Import jobs" ] } }, "/api/v1/recipes/import-previews/{preview_id}/measurement-resolution-groups/{group_id}": { "get": { "operationId": "get-measurement-resolution-group", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionGroupDetail" } } }, "description": "The group and every affected recipe ingredient." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Get a measurement group", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/measurement-resolution-plans": { "post": { "operationId": "create-measurement-resolution-plan", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionPlanInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionPlanResponse" } } }, "description": "The validated effects without changing the staged recipes." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Create a measurement plan", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/measurement-resolution-plans/{plan_id}": { "delete": { "operationId": "delete-measurement-resolution-plan", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionPlanApplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "The preview with the plan removed." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Delete a measurement plan", "tags": [ "Import" ] } }, "/api/v1/recipes/import-previews/{preview_id}/measurement-resolution-plans/{plan_id}/apply": { "post": { "operationId": "apply-measurement-resolution-plan", "parameters": [ { "in": "path", "name": "preview_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionPlanApplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementResolutionPlanResponse" } } }, "description": "The applied plan and revised import preview." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "summary": "Apply a measurement plan", "tags": [ "Import" ] } }, "/api/v1/recipes/import-url": { "post": { "description": "Fetches a public recipe page under Savorum's outbound policy and extracts its recipe. Structured data is read tolerantly: a page with one unreadable block and one good one still imports. A page that refused to answer, a page with no recipe on it, and a page whose recipe has no ingredients or method are reported as three different problems, because they are.", "operationId": "import-recipe-url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportURLInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Gateway Timeout" } }, "summary": "Import a web page", "tags": [ "Import" ] } }, "/api/v1/recipes/import-url/preview": { "post": { "description": "Fetches and interprets a public recipe page without changing the library. The response uses the same candidate and diagnostic model as uploaded JSON-LD and SREF files.", "operationId": "preview-recipe-url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportURLInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPreviewResponse" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" }, "504": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Gateway Timeout" } }, "summary": "Preview a web page", "tags": [ "Import" ] } }, "/api/v1/recipes/lookup": { "post": { "operationId": "get-recipes-summaries", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupOutputRecipeSummaryBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Resolve recipes selections", "tags": [ "Recipes" ] } }, "/api/v1/recipes/suggestions": { "get": { "operationId": "list-recipes-suggestions", "parameters": [ { "explode": false, "in": "query", "name": "q", "schema": { "maxLength": 200, "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 10, "format": "int64", "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionPageRecipeSummary" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Suggest recipes", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}": { "delete": { "operationId": "trash-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Strong ETag of the revision being changed", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the revision being changed", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Move a recipe to trash", "tags": [ "Recipes" ] }, "get": { "operationId": "get-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a recipe", "tags": [ "Recipes" ] }, "put": { "operationId": "replace-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Strong ETag of the revision being changed", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the revision being changed", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDocument" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a recipe", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/cookings": { "get": { "description": "Returns the remembered cookings, most recent first, with the count and most recent date derived from them.", "operationId": "list-recipe-cookings", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of cookings to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "description": "Maximum number of cookings to return", "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of cookings to skip", "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "description": "Number of cookings to skip", "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CookingHistory" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List cookings", "tags": [ "Cooking history" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-recipe-cooking", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CookingInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CookingRecord" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Record a cooking", "tags": [ "Cooking history" ] } }, "/api/v1/recipes/{id}/cookings/{cooking_id}": { "delete": { "operationId": "delete-recipe-cooking", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "cooking_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a cooking", "tags": [ "Cooking history" ] }, "put": { "operationId": "replace-recipe-cooking", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "cooking_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CookingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CookingRecord" } } }, "description": "OK", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a cooking", "tags": [ "Cooking history" ] } }, "/api/v1/recipes/{id}/export/sref": { "get": { "description": "Writes the stored recipe as a `.sref` package carrying every file it references. What travels is the recipe: this library's identifiers, revision numbers, tags, categories, books, ratings, notes, cooking history, and remembered batch stay behind, and so does whatever scaling or measurement the reader happens to be viewing. A recipe in the trash is still exportable until it is deleted permanently.", "operationId": "export-recipe-sref", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A `.sref` package." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Export a recipe", "tags": [ "Export" ] }, "head": { "description": "An export is generated on demand, so there is no response to describe without producing it. Use GET instead.", "operationId": "head-export-recipe-sref", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "405": { "description": "Method Not Allowed", "headers": { "Allow": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Head a recipe export", "tags": [ "Export" ] } }, "/api/v1/recipes/{id}/import-events": { "get": { "operationId": "list-recipe-import-events", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportHistoryOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List import events", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/organization": { "get": { "operationId": "get-recipe-organization", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeOrganization" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get recipe organization", "tags": [ "Organization" ] }, "put": { "description": "Replaces tags, categories, personal state, and provenance, and applies any named book membership changes in the same transaction.", "operationId": "replace-recipe-organization", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeOrganization" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace recipe organization", "tags": [ "Organization" ] } }, "/api/v1/recipes/{id}/reanalyze/microwave": { "post": { "operationId": "update-recipe-microwave-analysis", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Strong ETag of the revision being changed", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the revision being changed", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Reanalyze microwave timings", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/restore": { "post": { "operationId": "restore-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Strong ETag of the revision being changed", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the revision being changed", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Restore a recipe from trash", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/revisions": { "get": { "operationId": "list-recipe-revisions", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRevisionsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List recipe revisions", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/revisions/{revision}": { "get": { "operationId": "get-recipe-revision", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Historical revision number", "in": "path", "name": "revision", "required": true, "schema": { "description": "Historical revision number", "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRevision" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a recipe revision", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/revisions/{revision}/export/sref": { "get": { "description": "Writes a retained version exactly as the recipe read then. Export changes nothing, so an earlier version does not have to be restored to be kept, and the current version is unaffected.", "operationId": "export-recipe-revision-sref", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A `.sref` package." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Export a recipe revision", "tags": [ "Export" ] }, "head": { "description": "An export is generated on demand, so there is no response to describe without producing it. Use GET instead.", "operationId": "head-export-recipe-revision-sref", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "405": { "description": "Method Not Allowed", "headers": { "Allow": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Head a recipe revision export", "tags": [ "Export" ] } }, "/api/v1/recipes/{id}/revisions/{revision}/restore": { "post": { "operationId": "restore-recipe-revision", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Historical revision number", "in": "path", "name": "revision", "required": true, "schema": { "description": "Historical revision number", "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Strong ETag of the current revision", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the current revision", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Restore a recipe revision", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/source-refresh/preview-url": { "post": { "operationId": "preview-recipe-source-refresh", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRefreshURLInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRefreshPreviewWire" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Gateway" }, "504": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Gateway Timeout" } }, "summary": "Check a source URL", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/translations": { "get": { "description": "Renditions are separate recipes, each with its own address. Opening one never redirects to another.", "operationId": "list-recipe-translations", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeTranslations" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List a recipe's translations", "tags": [ "Recipes" ] }, "post": { "description": "Both recipes record the relationship in a new revision. Neither recipe's content changes.", "operationId": "create-recipe-translation-link", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTranslationInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangedEntriesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Link a recipe as a translation", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/translations/draft": { "post": { "description": "Returns an unsaved document for a new rendition. Nothing is stored. Copied content is ordinary text with no binding to this recipe.", "operationId": "start-recipe-translation", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftTranslationInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDocument" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Start a translation", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/translations/new": { "post": { "description": "Creates the new recipe and relates it to the recipe it translates. Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-recipe-translation", "parameters": [ { "description": "Library entry identifier of the recipe being translated", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier of the recipe being translated", "type": "string" } }, { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDocument" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Save a new translation", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{id}/translations/{counterpart}": { "delete": { "description": "Removes the declarations the two recipes make about each other. Both recipes remain.", "operationId": "unlink-recipe-translation", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Library entry of the other rendition", "in": "path", "name": "counterpart", "required": true, "schema": { "description": "Library entry of the other rendition", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangedEntriesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Unlink a translation", "tags": [ "Recipes" ] } }, "/api/v1/recipes/{recipe_id}/assets/{id}": { "get": { "operationId": "get-recipe-asset", "parameters": [ { "in": "path", "name": "recipe_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } } ], "responses": { "200": { "content": { "*/*": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The stored bytes. A conservative raster image is served inline with its own media type; any other type is an application/octet-stream attachment." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a recipe asset", "tags": [ "Assets" ] }, "head": { "operationId": "head-recipe-asset", "parameters": [ { "in": "path", "name": "recipe_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } }, "Content-Security-Policy": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Cross-Origin-Resource-Policy": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Head a recipe asset", "tags": [ "Assets" ] } }, "/api/v1/recipes/{recipe_id}/assets/{id}/derivatives/{preset}": { "get": { "operationId": "get-recipe-asset-derivative", "parameters": [ { "description": "Revalidate a cached image after checking current access", "in": "header", "name": "If-None-Match", "schema": { "description": "Revalidate a cached image after checking current access", "maxLength": 4096, "type": "string" } }, { "in": "path", "name": "recipe_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" } }, { "in": "path", "name": "preset", "required": true, "schema": { "pattern": "^(card|reader|thumb)$", "type": "string" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } }, "image/png": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "A resized image." }, "304": { "description": "The authorized derivative matches If-None-Match." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unsupported Media Type" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a recipe asset derivative", "tags": [ "Assets" ] } }, "/api/v1/saved-meals": { "get": { "operationId": "list-saved-meals", "parameters": [ { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMealsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List reusable meals", "tags": [ "Plan" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-saved-meal", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMealInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMeal" } } }, "description": "Created", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Save a reusable meal", "tags": [ "Plan" ] } }, "/api/v1/saved-meals/suggestions": { "get": { "operationId": "list-saved-meals-suggestions", "parameters": [ { "explode": false, "in": "query", "name": "q", "schema": { "maxLength": 200, "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 10, "format": "int64", "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionPageSavedMealSummary" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Suggest saved meals", "tags": [ "Plan" ] } }, "/api/v1/saved-meals/{id}": { "delete": { "operationId": "delete-saved-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a reusable meal", "tags": [ "Plan" ] }, "get": { "operationId": "get-saved-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMeal" } } }, "description": "OK", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a reusable meal", "tags": [ "Plan" ] }, "put": { "operationId": "replace-saved-meal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMealInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMeal" } } }, "description": "OK", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a reusable meal", "tags": [ "Plan" ] } }, "/api/v1/saved-meals/{id}/plan": { "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-meal-from-saved", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MealPlacementInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meal" } } }, "description": "Created", "headers": { "ETag": { "schema": { "description": "Validates this representation, including the recipe and shopping details it reads. If-Match takes the revision instead.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Plan a reusable meal", "tags": [ "Plan" ] } }, "/api/v1/saved-views": { "get": { "operationId": "list-saved-views", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List saved views", "tags": [ "Saved views" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-saved-view", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedView" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a saved view", "tags": [ "Saved views" ] } }, "/api/v1/saved-views/{id}": { "delete": { "operationId": "delete-saved-view", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a saved view", "tags": [ "Saved views" ] }, "get": { "operationId": "get-saved-view", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedView" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a saved view", "tags": [ "Saved views" ] }, "put": { "operationId": "replace-saved-view", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedView" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a saved view", "tags": [ "Saved views" ] } }, "/api/v1/saved-views/{id}/recipes": { "get": { "operationId": "list-saved-view-recipes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of entries to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "description": "Maximum number of entries to return", "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of entries to skip", "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "description": "Number of entries to skip", "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Present each set of translated recipes once, as the rendition the preferred languages choose among those that match", "explode": false, "in": "query", "name": "group_translations", "schema": { "description": "Present each set of translated recipes once, as the rendition the preferred languages choose among those that match", "type": "boolean" } }, { "description": "Comma-separated BCP 47 content languages in order of preference, used when grouping translations", "explode": false, "in": "query", "name": "languages", "schema": { "description": "Comma-separated BCP 47 content languages in order of preference, used when grouping translations", "maxLength": 1000, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRecipesOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "List saved view recipes", "tags": [ "Saved views" ] } }, "/api/v1/shopping/lists": { "get": { "operationId": "list-shopping-lists", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ShoppingListSummary" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List household shopping lists", "tags": [ "Shopping" ] }, "post": { "description": "The client chooses the list ID, so a retry with the same ID and name returns the same list. Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-shopping-list", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingListInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Create a named shopping list", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}": { "delete": { "description": "Removes the list, its items and its history. The household's Groceries list cannot be deleted.", "operationId": "delete-shopping-list", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Delete a named shopping list", "tags": [ "Shopping" ] }, "get": { "operationId": "get-groceries", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read the shared grocery list", "tags": [ "Shopping" ] }, "patch": { "operationId": "rename-shopping-list", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 100, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingListRename" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Rename a shopping list", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}/activity": { "get": { "operationId": "list-shopping-activity", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "description": "Return entries older than this entry identity", "explode": false, "in": "query", "name": "before", "schema": { "description": "Return entries older than this entry identity", "format": "int64", "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingActivityOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List shopping list activity", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}/apply": { "post": { "operationId": "apply-grocery-review", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 100, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingApplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Apply grocery choices", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}/changes": { "post": { "operationId": "change-groceries", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 100, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Apply a retryable grocery edit", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}/items": { "post": { "operationId": "create-grocery-items", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Create-grocery-itemsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingList" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Add groceries atomically", "tags": [ "Shopping" ] } }, "/api/v1/shopping/lists/{list_id}/review": { "post": { "operationId": "create-grocery-review", "parameters": [ { "in": "header", "name": "X-Savorum-Library", "schema": { "type": "string" } }, { "in": "header", "name": "X-Savorum-Principal", "schema": { "type": "string" } }, { "in": "path", "name": "list_id", "required": true, "schema": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingReviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingReview" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Review grocery requirements", "tags": [ "Shopping" ] } }, "/api/v1/storage-status": { "get": { "description": "Authenticated, bounded read of current combined hosted usage and filesystem headroom. Unknown measurements are omitted. This observation does not change write admission or start background polling.", "operationId": "get-storage-status", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerStorageStatus" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Observe storage capacity", "tags": [ "Instance" ] } }, "/api/v1/tags": { "get": { "operationId": "list-tags", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagsOutputBody" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List tags", "tags": [ "Tags" ] }, "post": { "description": " Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-tag", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" } }, "summary": "Create a tag", "tags": [ "Tags" ] } }, "/api/v1/tags/{id}": { "delete": { "operationId": "delete-tag", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a tag", "tags": [ "Tags" ] }, "get": { "operationId": "get-tag", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a tag", "tags": [ "Tags" ] }, "put": { "operationId": "replace-tag", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Replace a tag", "tags": [ "Tags" ] } }, "/api/v1/tags/{id}/merge": { "post": { "operationId": "merge-tag", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeTaxonomyInputBody" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Merge a tag", "tags": [ "Tags" ] } }, "/api/v1/trash/books/{id}": { "delete": { "description": "Permanently deletes the book and its retained revisions. Cover assets remain until reference-aware garbage collection proves that no retained object uses them.", "operationId": "delete-trashed-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a trashed book", "tags": [ "Books" ] }, "get": { "operationId": "get-trashed-book", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a trashed book", "tags": [ "Books" ] } }, "/api/v1/trash/empty": { "post": { "description": "Removes the named trashed recipes and books in one transaction. Every entry names the revision it was reviewed at, and the whole batch fails if any no longer matches.", "operationId": "empty-trash", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyTrashInputBody" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Empty the trash", "tags": [ "Recipes" ] } }, "/api/v1/trash/recipes/{id}": { "delete": { "description": "Permanently deletes the recipe, its retained revisions, and data owned solely by it. Referenced assets remain until reference-aware garbage collection proves that no retained object uses them.", "operationId": "delete-trashed-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } }, { "description": "Strong ETag of the revision being changed", "in": "header", "name": "If-Match", "schema": { "description": "Strong ETag of the revision being changed", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Required" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Delete a trashed recipe", "tags": [ "Recipes" ] }, "get": { "operationId": "get-trashed-recipe", "parameters": [ { "description": "Library entry identifier", "in": "path", "name": "id", "required": true, "schema": { "description": "Library entry identifier", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryEntry" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "summary": "Get a trashed recipe", "tags": [ "Recipes" ] } }, "/api/v1/users": { "get": { "description": "Instance administration. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "list-users", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersResponse" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "List users", "tags": [ "Users" ] }, "post": { "description": "Creates an ordinary local account. Instance administration. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "create-user", "parameters": [ { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUser" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Create a user", "tags": [ "Users" ] } }, "/api/v1/users/{id}": { "put": { "description": "Disables an account or resets its password. Instance administration. Uses the persisted local-mode user when authentication is disabled. Otherwise an authenticated browser session is required, except for the current account and sign-in. Modifying authenticated requests require the current X-CSRF-Token. Credentials and responses must not be cached.", "operationId": "update-user", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required with an authenticated browser session; read from current-account.", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "description": "Operation completed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "Stable account problem code; authentication, authority, validation or lifecycle conflict." } }, "summary": "Update a user", "tags": [ "Users" ] } }, "/api/v1/users/{id}/methods": { "get": { "description": "Instance administration. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "list-managed-user-sign-in-methods", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethodsResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "List a user's sign-in methods", "tags": [ "Sign-in methods" ] } }, "/api/v1/users/{id}/methods/{method}": { "delete": { "description": "Audited administrator action for a compromised identity. Browser session and CSRF protection are required for mutations, except invited local registration. Invitation secrets are returned once and must never be logged.", "operationId": "force-unlink-sign-in-method", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "method", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedResponse" } } }, "description": "Completed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." } }, "summary": "Force-unlink a sign-in method", "tags": [ "Sign-in methods" ] } }, "/api/v1/webhooks": { "get": { "description": "Library owners manage this library's subscriptions. Instance administrators manage instance security-event subscriptions through /instance-webhooks. Personal tokens cannot manage either. Destinations require HTTPS and public DNS addresses unless a deployment operator explicitly trusts a private CIDR. DNS is checked on each connection; up to three method-preserving HTTPS redirects are revalidated before following. Events contain IDs and minimal facts, never recipe bodies or credentials. Delivery is at least once. Receivers verify the exact body with HMAC-SHA256 over timestamp + '.' + body using Savorum-Signature: t=\u003cUnix seconds\u003e,v1=\u003chex\u003e, reject timestamps outside five minutes, then persistently deduplicate delivery_id. Savorum-Delivery-ID and Savorum-Event-ID also occur inside the signed body. Secrets appear once on create or rotate. Rotation immediately invalidates the old key for future attempts, including queued retries. Keep signing-key files with private instance backups. Retries cover network failures, 408, 429, and 5xx: up to eight attempts per cycle within 24 hours, exponential delay from 15 seconds with jitter, capped at one hour, honoring bounded Retry-After. Other statuses end the cycle. History retains up to 1000 finished deliveries per subscription for 30 days and 32 attempts per delivery. Repeated final failures automatically pause delivery; fix the receiver before re-enabling. Paused subscriptions retain queued work but do not subscribe to new events.", "operationId": "list-webhooks", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Subscription" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List library webhooks", "tags": [ "Webhooks" ] }, "post": { "description": "Library owners manage this library's subscriptions. Instance administrators manage instance security-event subscriptions through /instance-webhooks. Personal tokens cannot manage either. Destinations require HTTPS and public DNS addresses unless a deployment operator explicitly trusts a private CIDR. DNS is checked on each connection; up to three method-preserving HTTPS redirects are revalidated before following. Events contain IDs and minimal facts, never recipe bodies or credentials. Delivery is at least once. Receivers verify the exact body with HMAC-SHA256 over timestamp + '.' + body using Savorum-Signature: t=\u003cUnix seconds\u003e,v1=\u003chex\u003e, reject timestamps outside five minutes, then persistently deduplicate delivery_id. Savorum-Delivery-ID and Savorum-Event-ID also occur inside the signed body. Secrets appear once on create or rotate. Rotation immediately invalidates the old key for future attempts, including queued retries. Keep signing-key files with private instance backups. Retries cover network failures, 408, 429, and 5xx: up to eight attempts per cycle within 24 hours, exponential delay from 15 seconds with jitter, capped at one hour, honoring bounded Retry-After. Other statuses end the cycle. History retains up to 1000 finished deliveries per subscription for 30 days and 32 attempts per delivery. Repeated final failures automatically pause delivery; fix the receiver before re-enabling. Paused subscriptions retain queued work but do not subscribe to new events. Creation accepts Idempotency-Key; reuse it only with the same request. Receipts last at least 24 hours.", "operationId": "create-webhook", "parameters": [ { "description": "Optional retry key. Receipts retain the created identity for at least 24 hours. A replay returns the current authorized resource; one-time secrets are omitted.", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Creation retry refused" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Create library webhook", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}": { "delete": { "operationId": "delete-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Delete library webhook", "tags": [ "Webhooks" ] }, "get": { "operationId": "get-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read library webhook", "tags": [ "Webhooks" ] }, "put": { "operationId": "update-webhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Update library webhook", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "list-webhook-deliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "format": "int64", "maximum": 1000, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Delivery" }, "type": [ "array", "null" ] } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "List library deliveries", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}/deliveries/{delivery_id}": { "get": { "operationId": "get-webhook-delivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Detail" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Read library delivery", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}/deliveries/{delivery_id}/redeliver": { "post": { "operationId": "create-webhook-redelivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Create-webhook-redeliveryResponse" } } }, "description": "Accepted" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Retry library delivery", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}/rotate-secret": { "post": { "description": "The old secret is retired as soon as rotation completes. All future attempts, including retries of existing deliveries, use the new secret. Install the returned secret before re-enabling a paused subscription. The secret cannot be read later.", "operationId": "replace-webhook-secret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Rotate library key", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/{id}/test": { "post": { "operationId": "create-webhook-test", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } }, "description": "Accepted" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/AccountProblem" } } }, "description": "No valid session or API token (`authentication-required`), or the credential sent is invalid (`invalid-credentials`)." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Test library webhook", "tags": [ "Webhooks" ] } } }, "security": [ { "bearerToken": [] }, { "browserSession": [] } ], "servers": [ { "description": "A local instance on its default listener.", "url": "http://127.0.0.1:8080" } ], "tags": [ { "description": "The container a recipe lives in. Everything below is scoped to one.", "name": "Libraries" }, { "description": "Recipe entries, their revisions, and trash and restore.", "name": "Recipes" }, { "description": "Author-name discovery from the selected library's active recipes.", "name": "Recipe authors" }, { "description": "Dated and unscheduled meals, plus reusable meal combinations.", "name": "Plan" }, { "description": "Shared grocery lists and reviewed ingredient requirements.", "name": "Shopping" }, { "description": "A recipe's library-owned layer: tags, facets, and personal state.", "name": "Organization" }, { "description": "Records of having cooked a recipe.", "name": "Cooking history" }, { "description": "Curated collections, their chapters, and publication provenance.", "name": "Books" }, { "description": "The library's tag catalog.", "name": "Tags" }, { "description": "Course, cuisine, method, and dietary catalogs.", "name": "Facets" }, { "description": "Stored library queries.", "name": "Saved views" }, { "description": "Immutable content-addressed uploads and their delivery.", "name": "Assets" }, { "description": "Bring recipes in from files, third-party exports, and web pages, and review a staged preview before committing it.", "name": "Import" }, { "description": "The background lifecycle of a committed import: progress, per-recipe outcomes, cancellation, and resumption.", "name": "Import jobs" }, { "description": "Portable recipe and collection downloads as SREF documents, packages, and bundles.", "name": "Export" }, { "description": "Rendered PDF documents for pages and recipe cards.", "name": "Print" }, { "description": "The signed-in account itself: who it is, its password, its preferences, its audit history, and the library it is acting in.", "name": "Account" }, { "description": "Signing in and out, and the browser sessions an account holds.", "name": "Sessions" }, { "description": "WebAuthn registration and usernameless sign-in.", "name": "Passkeys" }, { "description": "Single-use codes for regaining access to an account.", "name": "Recovery codes" }, { "description": "Personal bearer credentials for integrations.", "name": "API tokens" }, { "description": "Who holds a role in a library, and administrator recovery of its ownership.", "name": "Library members" }, { "description": "Inviting someone to a library and accepting the invitation.", "name": "Invitations" }, { "description": "The identities attached to an account, and the providers they depend on.", "name": "Sign-in methods" }, { "description": "External identity providers, the sign-in flows they use, and the mapping from their groups to library roles.", "name": "Authentication" }, { "description": "Account administration for the instance.", "name": "Users" }, { "description": "Signed external delivery, owner-managed destinations, attempts, and failure controls.", "name": "Webhooks" }, { "description": "Authorized change notifications; refresh through normal resource APIs.", "name": "Events" }, { "description": "Bounded recipe operations using ordinary resource authorization and revisions.", "name": "Bulk" }, { "description": "Typed bulk and transfer work, retained for 24 hours.", "name": "Jobs" }, { "description": "Optional household presence and approximate stock, reviewed explicitly.", "name": "Pantry" }, { "description": "The settings, capabilities, and readiness a client may read.", "name": "Instance" } ] }