{"openapi":"3.1.0","info":{"title":"KvittoApp API","version":"1","description":"For external integrations. Authenticate with an API key as a bearer token. Changes to existing records need If-Match with the rev from the ETag; POSTs may send an Idempotency-Key."},"servers":[{"url":"/api/v1"}],"tags":[{"name":"Key","description":"The calling API key: its owner, and what it may do right now."},{"name":"Receipts","description":"Receipts with their line items, tags and photo, and the registry companies they point at."},{"name":"Categories and tags","description":"How the household organises its receipts."},{"name":"Reports","description":"Across many receipts: what changed since a cursor, totals, and export."},{"name":"Admin: users","description":"Who may use the server, and with which role. Needs an admin scope."},{"name":"Admin: devices and pairing","description":"Pairing codes, paired apps and dashboard sign-ins."},{"name":"Admin: API keys","description":"Keys for integrations. Only admins create or revoke them."},{"name":"Admin: settings and secrets","description":"Sign-in and AI settings, and the server's provider keys."},{"name":"Admin: local model","description":"The on-server receipt reader and its queue."},{"name":"Admin: diagnostics","description":"The diagnostic log and record counts."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}}},"security":[{"apiKey":[]}],"paths":{"/me":{"get":{"tags":["Key"],"summary":"The calling key: its scopes, what its owner's role allows of them now, and its owner.","description":"Any valid API key.","x-scope":null,"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts":{"get":{"tags":["Receipts"],"summary":"List receipts, newest purchase first, with filters and cursor paging.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"tagId","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"include","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"post":{"tags":["Receipts"],"summary":"Create a receipt. JSON for manual entry; multipart with an `image` file (and optional `data` JSON) to add a photo.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"},"merchant":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"],"maxLength":256},"orgNumber":{"type":["string","null"],"maxLength":32},"vatNumber":{"type":["string","null"],"maxLength":32},"address":{"type":["string","null"],"maxLength":256},"postalCode":{"type":["string","null"],"maxLength":16},"city":{"type":["string","null"],"maxLength":128},"country":{"type":["string","null"],"maxLength":64},"phone":{"type":["string","null"],"maxLength":64},"storeId":{"type":["string","null"],"maxLength":64}}},"purchasedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"total":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"subtotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"discountTotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"roundingAmount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"depositTotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vatLines":{"type":"array","maxItems":10,"items":{"type":"object","required":["rate"],"additionalProperties":false,"properties":{"rate":{"type":"number","minimum":0,"maximum":100},"net":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vat":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"gross":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000}}}},"paymentMethod":{"type":["string","null"],"maxLength":64},"cardLast4":{"type":["string","null"],"pattern":"^[0-9]{4}$"},"receiptNumber":{"type":["string","null"],"maxLength":64},"terminalId":{"type":["string","null"],"maxLength":64},"cashier":{"type":["string","null"],"maxLength":64},"categoryId":{"type":["string","null"],"minLength":1,"maxLength":128},"companyId":{"type":["string","null"],"minLength":1,"maxLength":128},"notes":{"type":["string","null"],"maxLength":10000},"status":{"type":"string","enum":["draft","parsed","confirmed"]},"items":{"type":"array","maxItems":500,"items":{"type":"object","required":["name","totalPrice"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"},"name":{"type":"string","minLength":1,"maxLength":512},"rawName":{"type":["string","null"],"maxLength":512},"quantity":{"type":"number","minimum":-1000000,"maximum":1000000},"unit":{"type":"string","enum":["st","kg","hg","g","l","dl","cl","m","förp","other"]},"unitPrice":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"totalPrice":{"type":"number","minimum":-1000000000,"maximum":1000000000},"discount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vatRate":{"type":["number","null"],"minimum":0,"maximum":100},"categoryId":{"type":["string","null"],"minLength":1,"maxLength":128},"ean":{"type":["string","null"],"pattern":"^[0-9]{8,14}$"},"deposit":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"isDeposit":{"type":"boolean"},"isDiscount":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":2000}}}},"tagIds":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128}}}}},"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"A JPEG, PNG, PDF or TIFF file of at most 8 MB, checked by its contents."},"data":{"type":"string","description":"JSON: the same fields as the application/json body."}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts/{id}":{"get":{"tags":["Receipts"],"summary":"One receipt. `include=items,tags,company` adds those.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"include","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"patch":{"tags":["Receipts"],"summary":"Change some of a receipt's fields. Requires `If-Match`.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"merchant":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"],"maxLength":256},"orgNumber":{"type":["string","null"],"maxLength":32},"vatNumber":{"type":["string","null"],"maxLength":32},"address":{"type":["string","null"],"maxLength":256},"postalCode":{"type":["string","null"],"maxLength":16},"city":{"type":["string","null"],"maxLength":128},"country":{"type":["string","null"],"maxLength":64},"phone":{"type":["string","null"],"maxLength":64},"storeId":{"type":["string","null"],"maxLength":64}}},"purchasedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"total":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"subtotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"discountTotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"roundingAmount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"depositTotal":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vatLines":{"type":"array","maxItems":10,"items":{"type":"object","required":["rate"],"additionalProperties":false,"properties":{"rate":{"type":"number","minimum":0,"maximum":100},"net":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vat":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"gross":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000}}}},"paymentMethod":{"type":["string","null"],"maxLength":64},"cardLast4":{"type":["string","null"],"pattern":"^[0-9]{4}$"},"receiptNumber":{"type":["string","null"],"maxLength":64},"terminalId":{"type":["string","null"],"maxLength":64},"cashier":{"type":["string","null"],"maxLength":64},"categoryId":{"type":["string","null"],"minLength":1,"maxLength":128},"companyId":{"type":["string","null"],"minLength":1,"maxLength":128},"notes":{"type":["string","null"],"maxLength":10000},"status":{"type":"string","enum":["draft","parsed","confirmed"]}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"delete":{"tags":["Receipts"],"summary":"Delete a receipt, with its items and tag links. Requires `If-Match`.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts/{id}/items":{"put":{"tags":["Receipts"],"summary":"Replace a receipt's line items. Items named by `id` are updated, new ones created, missing ones deleted. Requires the receipt's `If-Match`.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"additionalProperties":false,"properties":{"items":{"type":"array","maxItems":500,"items":{"type":"object","required":["name","totalPrice"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"},"name":{"type":"string","minLength":1,"maxLength":512},"rawName":{"type":["string","null"],"maxLength":512},"quantity":{"type":"number","minimum":-1000000,"maximum":1000000},"unit":{"type":"string","enum":["st","kg","hg","g","l","dl","cl","m","förp","other"]},"unitPrice":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"totalPrice":{"type":"number","minimum":-1000000000,"maximum":1000000000},"discount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"vatRate":{"type":["number","null"],"minimum":0,"maximum":100},"categoryId":{"type":["string","null"],"minLength":1,"maxLength":128},"ean":{"type":["string","null"],"pattern":"^[0-9]{8,14}$"},"deposit":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"isDeposit":{"type":"boolean"},"isDiscount":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":2000}}}}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts/{id}/tags":{"put":{"tags":["Receipts"],"summary":"Set exactly which tags a receipt has. Requires the receipt's `If-Match`.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagIds"],"additionalProperties":false,"properties":{"tagIds":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128}}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts/{id}/image":{"get":{"tags":["Receipts"],"summary":"The receipt's image. `variant=processed` (default), `original` or `thumbnail`.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"variant","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"put":{"tags":["Receipts"],"summary":"Replace the receipt's photo: the raw bytes of a JPEG, PNG, PDF or TIFF file of at most 8 MB, checked by its contents; `Content-Type` must match them or be application/octet-stream. Requires `If-Match`. Queues extraction when the local model is on.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/tiff":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/receipts/{id}/extract":{"post":{"tags":["Receipts"],"summary":"Read the receipt's image again with the server's local model.","description":"Scope: `receipts:write`","x-scope":"receipts:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/companies/{id}":{"get":{"tags":["Receipts"],"summary":"A company from the registry, by the id a receipt's `companyId` names.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/categories":{"get":{"tags":["Categories and tags"],"summary":"Every category, in the order the apps show them.","description":"Scope: `receipts:read`","x-scope":"receipts:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"post":{"tags":["Categories and tags"],"summary":"Create a category.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"},"name":{"type":"string","minLength":1,"maxLength":64},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"icon":{"type":["string","null"],"maxLength":16},"parentId":{"type":["string","null"],"minLength":1,"maxLength":128},"scope":{"type":"string","enum":["receipt","item","both"]},"sortOrder":{"type":"integer","minimum":-1000000,"maximum":1000000}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/categories/{id}":{"patch":{"tags":["Categories and tags"],"summary":"Change a category. Requires `If-Match`.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"icon":{"type":["string","null"],"maxLength":16},"parentId":{"type":["string","null"],"minLength":1,"maxLength":128},"scope":{"type":"string","enum":["receipt","item","both"]},"sortOrder":{"type":"integer","minimum":-1000000,"maximum":1000000}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"delete":{"tags":["Categories and tags"],"summary":"Delete a category. Receipts and items in it move to `reassignTo`, or to no category; subcategories move to the top level. Requires `If-Match`.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"reassignTo","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/tags":{"get":{"tags":["Categories and tags"],"summary":"Every tag, in the order the apps show them.","description":"Scope: `receipts:read`","x-scope":"receipts:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"post":{"tags":["Categories and tags"],"summary":"Create a tag.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"},"name":{"type":"string","minLength":1,"maxLength":64},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"sortOrder":{"type":"integer","minimum":-1000000,"maximum":1000000}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/tags/{id}":{"patch":{"tags":["Categories and tags"],"summary":"Change a tag. Requires `If-Match`.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"sortOrder":{"type":"integer","minimum":-1000000,"maximum":1000000}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"delete":{"tags":["Categories and tags"],"summary":"Delete a tag and remove it from every receipt. Requires `If-Match`.","description":"Scope: `taxonomy:write`","x-scope":"taxonomy:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/changes":{"get":{"tags":["Reports"],"summary":"What changed since `since` (a cursor from a previous call; 0 for everything): type, id, rev and whether it was deleted. Fetch the records you need. If `epoch` changes, the server was rebuilt: start again from 0.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/stats/summary":{"get":{"tags":["Reports"],"summary":"Receipt count, total and VAT per month, category or merchant, and per currency, for purchases between `from` and `to` (inclusive, YYYY-MM-DD).","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"groupBy","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/export":{"get":{"tags":["Reports"],"summary":"`format=csv` (default): one row per receipt, VAT per rate. `format=zip`: the CSV plus each receipt's photo, at most 500 receipts per export.","description":"Scope: `receipts:read`","x-scope":"receipts:read","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/users":{"get":{"tags":["Admin: users"],"summary":"Every user, with role and number of active devices.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"post":{"tags":["Admin: users"],"summary":"Add an admin, with a password. Regular users are created by redeeming a pairing code.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password","role"],"additionalProperties":false,"properties":{"username":{"type":"string","minLength":1,"maxLength":128},"password":{"type":"string","minLength":1,"maxLength":256},"role":{"type":"string","enum":["admin"]}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/users/{id}":{"patch":{"tags":["Admin: users"],"summary":"Change a user's role. Promoting to admin needs a `password`. Demoting drops the password, signs out their dashboard sessions, and takes admin scopes from their API keys at once. The last admin cannot be demoted.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"additionalProperties":false,"properties":{"role":{"type":"string","enum":["user","admin"]},"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"delete":{"tags":["Admin: users"],"summary":"Remove a user and revoke every device and API key they have, possibly the calling key. The last admin cannot be removed.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/pairing-codes":{"post":{"tags":["Admin: devices and pairing"],"summary":"A one-time pairing code, with its QR payload. `username` makes a new user; `userId` adds a device to an existing one.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"serverUrl":{"type":"string","maxLength":2048},"username":{"type":"string","maxLength":128},"userId":{"type":"string","maxLength":128}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/devices":{"get":{"tags":["Admin: devices and pairing"],"summary":"Paired apps and dashboard sign-ins. API keys are under /admin/keys.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/devices/{id}":{"delete":{"tags":["Admin: devices and pairing"],"summary":"Revoke a paired app or a dashboard sign-in.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/keys":{"get":{"tags":["Admin: API keys"],"summary":"Every API key, revoked ones included. Never the token.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"post":{"tags":["Admin: API keys"],"summary":"Create an API key for a user. Scopes are capped by the user's role and by the calling key's own scopes. The token is in this response and nowhere else.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","name","scopes"],"additionalProperties":false,"properties":{"userId":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":64},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["receipts:read","receipts:write","taxonomy:write","admin:read","admin:write"]}},"expiresAt":{"type":["string","null"],"maxLength":64}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/keys/{id}":{"delete":{"tags":["Admin: API keys"],"summary":"Revoke an API key.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/settings":{"get":{"tags":["Admin: settings and secrets"],"summary":"Sign-in and AI settings. Says whether the AI key is set, never what it is.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/settings/auth":{"put":{"tags":["Admin: settings and secrets"],"summary":"`disableOnLan`: skip sign-in for private addresses (never for /api/v1); null follows the environment.","description":"Scope: `admin:write`","x-scope":"admin:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["disableOnLan"],"additionalProperties":false,"properties":{"disableOnLan":{"type":["boolean","null"]}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/settings/ai":{"put":{"tags":["Admin: settings and secrets"],"summary":"The server's AI provider settings, whole, as `{ ai: { ... } }`, and/or the queue's retry limit as `{ queue: { maxRetriesPerHour } }`.","description":"Scope: `admin:write`","x-scope":"admin:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"queue":{"type":"object","required":["maxRetriesPerHour"],"additionalProperties":false,"properties":{"maxRetriesPerHour":{"type":"integer","minimum":0,"maximum":1000}}},"ai":{"type":"object","required":["provider","model","baseUrl","maxOutputTokens","effort","structuredOutput","extraInstructions"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["none","anthropic","openai","openai-compatible"]},"model":{"type":"string","minLength":1,"maxLength":128},"baseUrl":{"type":"string","maxLength":2048},"maxOutputTokens":{"type":"integer","minimum":1000,"maximum":128000},"effort":{"type":"string","enum":["auto","low","medium","high","xhigh","max"]},"structuredOutput":{"type":"boolean"},"extraInstructions":{"type":"string","maxLength":2000}}}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/secrets":{"get":{"tags":["Admin: settings and secrets"],"summary":"Which provider keys are set, and when they changed. Never their values.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/secrets/{id}":{"put":{"tags":["Admin: settings and secrets"],"summary":"Set a provider key; an empty `value` clears it. The value is never returned.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aiApiKey","companyApiKey","bolagsverketClientId","bolagsverketClientSecret"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"additionalProperties":false,"properties":{"value":{"type":"string","maxLength":16384}}}}}},"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/llm":{"get":{"tags":["Admin: local model"],"summary":"The local model: runtime state, installed models, queue and recent failures.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/llm/start":{"post":{"tags":["Admin: local model"],"summary":"Start the model runtime now.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/llm/pull":{"post":{"tags":["Admin: local model"],"summary":"Download the model; progress is in GET /admin/llm.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/llm/scan":{"post":{"tags":["Admin: local model"],"summary":"Run an extraction pass now; optional `{ size }`, at most 25.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/llm/requeue":{"post":{"tags":["Admin: local model"],"summary":"Queue `{ receiptId }` again, or every failed receipt.","description":"Scope: `admin:write`","x-scope":"admin:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/logs":{"get":{"tags":["Admin: diagnostics"],"summary":"The diagnostic log, newest first; secrets redacted. Filter with `level`, `category`, `since`.","description":"Scope: `admin:read`","x-scope":"admin:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"since","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"level","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"category","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}},"delete":{"tags":["Admin: diagnostics"],"summary":"Clear the diagnostic log.","description":"Scope: `admin:write`","x-scope":"admin:write","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}},"/admin/stats":{"get":{"tags":["Admin: diagnostics"],"summary":"Stored records per kind, the current revision and the history epoch.","description":"Scope: `admin:read`","x-scope":"admin:read","responses":{"default":{"description":"JSON. Errors are `{ error, message }`; `error` is the stable code to act on."}}}}}}