{"openapi":"3.0.0","info":{"title":"EuGasto API","version":"0.1.0","description":"Versioned HTTP API. The web app and API keys call the shared domain services. Send a session cookie, or Authorization: Bearer with a personal API key. Amounts are integer minor units. Every workspace route is limited to a workspace the caller belongs to."},"components":{"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"time":{"type":"string","format":"date-time"}},"required":["status","service","time"]},"Me":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"image":{"type":"string","nullable":true},"locale":{"type":"string","enum":["pt-PT","en"],"description":"Saved language. Null in the database reads as pt-PT. Change it with POST /api/auth/update-user { locale }."},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2. Null until the user answers. Change it with POST /api/auth/update-user { country }.","example":"PT"},"termsAcceptedAt":{"type":"string","nullable":true,"format":"date-time","description":"When the terms of service and privacy policy were accepted at sign-up. Null for accounts created before terms acceptance was recorded."},"termsVersion":{"type":"string","nullable":true,"description":"Version of the accepted terms, e.g. \"2026-11-17\"."}},"required":["id","name","email","image","locale","country","termsAcceptedAt","termsVersion"]},"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]},"status":{"type":"string","enum":["active","invited"]},"plan":{"type":"string"},"baseCurrency":{"type":"string"},"categoryCount":{"type":"integer"},"memberCount":{"type":"integer","description":"Active members of the space, including the caller."}},"required":["id","name","slug","role","status","plan","baseCurrency","categoryCount","memberCount"]}},"limits":{"type":"object","properties":{"ownedSpaces":{"type":"integer"},"ownedSpaceLimit":{"type":"integer","nullable":true}},"required":["ownedSpaces","ownedSpaceLimit"]},"features":{"type":"object","properties":{"invoiceQr":{"type":"boolean","description":"Show the seller NIF field and the Portuguese invoice QR scanner: FEATURE_INVOICE_QR is \"on\" and user.country is \"PT\". UI gate only; the API accepts sellerVat and invoiceQr from any authorised caller. The scanner also needs an EUR space."}},"required":["invoiceQr"],"description":"Server-computed UI gates. Clients must not derive them."}},"required":["user","workspaces","limits","features"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Hints":{"type":"object","properties":{"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 guessed from the request (Cloudflare cf.country). Null when unknown, local, Tor (T1) or XX. A suggestion only; never saved.","example":"PT"},"locale":{"type":"string","enum":["pt-PT","en"],"description":"Supported locale picked from Accept-Language (pt-PT by default)."}},"required":["country","locale"]},"AccountDeletion":{"type":"object","properties":{"password":{"type":"string","minLength":1,"maxLength":256,"description":"The user's current password, re-checked before anything is deleted."}},"required":["password"]},"WorkspaceSettings":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"baseCurrency":{"type":"string"}},"required":["id","name","slug","baseCurrency"]},"WorkspaceUpdate":{"type":"object","properties":{"name":{"type":"string"},"baseCurrency":{"type":"string"}}},"Expense":{"type":"object","properties":{"id":{"type":"string"},"amountMinor":{"type":"number"},"currency":{"type":"string"},"baseAmountMinor":{"type":"number"},"spentOn":{"type":"string"},"payee":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"category":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}},"required":["id","name","icon","color"]},"account":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["id","name","type"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"receipts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"byteSize":{"type":"number"}},"required":["id","filename","contentType","byteSize"]}},"importId":{"type":"string","nullable":true},"sellerVat":{"type":"string","nullable":true,"description":"Seller's Portuguese NIF, from the invoice QR (field A) or typed."},"invoice":{"$ref":"#/components/schemas/ExpenseInvoice"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","amountMinor","currency","baseAmountMinor","spentOn","payee","note","category","account","tags","receipts","importId","sellerVat","invoice","createdAt","updatedAt"]},"ExpenseInvoice":{"type":"object","nullable":true,"properties":{"docType":{"type":"string","description":"QR D (SAF-T type): FT, FS, FR or ND.","example":"FS"},"docStatus":{"type":"string","description":"QR E: N, S or R.","example":"N"},"docId":{"type":"string","description":"QR G as printed (trimmed).","example":"FS CDVF/12345"},"atcud":{"type":"string","nullable":true,"description":"QR H (trimmed). Null when missing or \"0\".","example":"CDF7T5HD-12345"},"docDate":{"type":"string","description":"QR F as YYYY-MM-DD."},"buyerCountry":{"type":"string","nullable":true,"description":"QR C."},"buyerHasNif":{"type":"boolean","description":"QR B is a real NIF (not 999999990). The buyer NIF itself is never stored or returned."},"grossTotalMinor":{"type":"integer","description":"QR O, euro cents."},"taxTotalMinor":{"type":"integer","description":"QR N, euro cents."},"withholdingMinor":{"type":"integer","nullable":true,"description":"QR P (withholding tax), euro cents."},"stampDutyMinor":{"type":"integer","nullable":true,"description":"QR M (stamp duty), euro cents."},"notSubjectMinor":{"type":"integer","nullable":true,"description":"QR L (not subject to VAT), euro cents."},"taxBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceTaxRegion"},"description":"VAT per fiscal space (I, J, K blocks). Empty when the document shows none."},"source":{"type":"string","description":"How the QR was read: camera, photo, text, api or mcp."}},"required":["docType","docStatus","docId","atcud","docDate","buyerCountry","buyerHasNif","grossTotalMinor","taxTotalMinor","withholdingMinor","stampDutyMinor","notSubjectMinor","taxBreakdown","source"],"description":"Snapshot of the fiscal document when the expense was recorded from an AT invoice QR code."},"InvoiceTaxRegion":{"type":"object","properties":{"block":{"type":"string","enum":["I","J","K"],"description":"QR block."},"region":{"type":"string","description":"I1/J1/K1: \"PT\", \"PT-AC\", \"PT-MA\" or an ISO code."},"exemptBaseMinor":{"type":"integer","description":"x2, euro cents. 0 when absent."},"reducedBaseMinor":{"type":"integer","description":"x3, euro cents. 0 when absent."},"reducedVatMinor":{"type":"integer","description":"x4, euro cents. 0 when absent."},"intermediateBaseMinor":{"type":"integer","description":"x5, euro cents. 0 when absent."},"intermediateVatMinor":{"type":"integer","description":"x6, euro cents. 0 when absent."},"normalBaseMinor":{"type":"integer","description":"x7, euro cents. 0 when absent."},"normalVatMinor":{"type":"integer","description":"x8, euro cents. 0 when absent."}},"required":["block","region","exemptBaseMinor","reducedBaseMinor","reducedVatMinor","intermediateBaseMinor","intermediateVatMinor","normalBaseMinor","normalVatMinor"]},"CreateExpenseConflict":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"POSSIBLE_DUPLICATE"},"message":{"type":"string"},"duplicates":{"type":"array","items":{"$ref":"#/components/schemas/PossibleDuplicate"},"maxItems":5,"description":"Only for POSSIBLE_DUPLICATE: the matching expenses, at most 5, newest first (createdAt descending)."}},"required":["code","message"]}},"required":["error"]},"PossibleDuplicate":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string","description":"The expense date (spentOn), YYYY-MM-DD."},"amount":{"type":"integer","description":"Integer minor units."},"currency":{"type":"string"},"payee":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","date","amount","currency","payee","note","createdAt"]},"ExpenseWrite":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Integer minor units. Required unless invoiceQr is sent; then it defaults to the invoice gross total O (euro cents)."},"spentOn":{"type":"string","description":"YYYY-MM-DD. Required unless invoiceQr is sent; then it defaults to the invoice date F."},"categoryId":{"type":"string","nullable":true},"accountId":{"type":"string","nullable":true},"payee":{"type":"string","nullable":true},"note":{"type":"string","nullable":true,"description":"Free text. With invoiceQr and no note in the body, the invoice's document id G is used."},"tagIds":{"type":"array","items":{"type":"string"}},"currency":{"type":"string"},"sellerVat":{"type":"string","nullable":true,"maxLength":20,"description":"Seller's Portuguese NIF. Spaces, dots, dashes and a \"PT\" prefix are stripped; it must be a valid 9-digit NIF other than 999999990 (invalid_nif). Null clears it. With invoiceQr it must equal QR field A (invoice_qr_mismatch); on an expense with an invoice it cannot change (invoice_field_locked). Saving with a sellerVat and a payee updates the space's learned seller mapping.","example":"123456789"},"invoiceQr":{"type":"string","maxLength":1024,"description":"Create only. The exact text inside a Portuguese invoice QR code (starts with \"A:\"), passed verbatim. The server parses it again, refuses credit notes, receipts, working and transport documents and cancelled invoices, rejects duplicates in the space (409 duplicate_invoice), and stores a snapshot (never the buyer NIF or the raw text). Amounts are euros, so the space must be EUR (single_currency). On PATCH: 409 invoice_already_linked if one is linked, else 400 (attach is not available yet)."},"invoiceSource":{"type":"string","enum":["camera","photo","text"],"description":"How invoiceQr was read: camera, photo or text. Stored on the invoice snapshot; defaults to \"api\"."},"allowDuplicate":{"type":"boolean","description":"Create only (ignored on PATCH). Default false. When the expense looks like one already in the space (same amount, currency and date, and a similar payee or the same HH:MM time in both notes), the create fails with 409 POSSIBLE_DUPLICATE and nothing is written. Send true to save it anyway."}}},"InvoiceQrPreview":{"type":"object","properties":{"invoice":{"type":"object","properties":{"docType":{"type":"string","description":"QR D (SAF-T type): FT, FS, FR or ND.","example":"FS"},"docStatus":{"type":"string","description":"QR E: N, S or R.","example":"N"},"docId":{"type":"string","description":"QR G as printed (trimmed).","example":"FS CDVF/12345"},"atcud":{"type":"string","nullable":true,"description":"QR H (trimmed). Null when missing or \"0\".","example":"CDF7T5HD-12345"},"docDate":{"type":"string","description":"QR F as YYYY-MM-DD."},"buyerCountry":{"type":"string","nullable":true,"description":"QR C."},"buyerHasNif":{"type":"boolean","description":"QR B is a real NIF (not 999999990). The buyer NIF itself is never stored or returned."},"grossTotalMinor":{"type":"integer","description":"QR O, euro cents."},"taxTotalMinor":{"type":"integer","description":"QR N, euro cents."},"withholdingMinor":{"type":"integer","nullable":true,"description":"QR P (withholding tax), euro cents."},"stampDutyMinor":{"type":"integer","nullable":true,"description":"QR M (stamp duty), euro cents."},"notSubjectMinor":{"type":"integer","nullable":true,"description":"QR L (not subject to VAT), euro cents."},"taxBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceTaxRegion"},"description":"VAT per fiscal space (I, J, K blocks). Empty when the document shows none."}},"required":["docType","docStatus","docId","atcud","docDate","buyerCountry","buyerHasNif","grossTotalMinor","taxTotalMinor","withholdingMinor","stampDutyMinor","notSubjectMinor","taxBreakdown"],"description":"What the server parsed. No source: nothing is stored. The seller NIF is proposal.sellerVat."},"proposal":{"type":"object","properties":{"amountMinor":{"type":"integer","description":"Always O, the invoice gross total (euro cents)."},"netOfWithholdingMinor":{"type":"integer","description":"O − P. Present only when P > 0 and O − P > 0."},"spentOn":{"type":"string","description":"F as YYYY-MM-DD."},"sellerVat":{"type":"string","description":"A."},"note":{"type":"string","description":"G, the document id."}},"required":["amountMinor","spentOn","sellerVat","note"]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"field":{"type":"string"}},"required":["code"]},"description":"Parser and policy notes, e.g. whitespace, old_date, withholding, debit_note, atcud_missing, totals_mismatch. Codes are stable; field is a QR field code."},"duplicateOf":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"spentOn":{"type":"string"},"amountMinor":{"type":"integer"},"payee":{"type":"string","nullable":true}},"required":["id","spentOn","amountMinor","payee"],"description":"The expense that already records this document in the space (same seller and document id, or same ATCUD). Saving would fail with 409 duplicate_invoice."},"suggestion":{"type":"object","nullable":true,"properties":{"source":{"type":"string","enum":["learned","vies"]},"payee":{"type":"string","nullable":true},"categoryId":{"type":"string","nullable":true},"accountId":{"type":"string","nullable":true}},"required":["source","payee","categoryId","accountId"],"description":"Payee prefill. \"learned\": the space's last payee, category and account for this NIF (archived ones dropped to null). \"vies\": the EU VIES registered name for a company NIF (5, 6, 9) when nothing is learned; categoryId and accountId are always null. Null when neither applies or VIES fails."}},"required":["invoice","proposal","warnings","duplicateOf","suggestion"]},"InvoiceQrPreviewRequest":{"type":"object","properties":{"qr":{"type":"string","maxLength":1024,"description":"The exact text inside the QR code (starts with \"A:\"), verbatim."}},"required":["qr"]},"OtherCurrencyTotals":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amountMinor":{"type":"integer"},"count":{"type":"integer"}},"required":["currency","amountMinor","count"]}},"ImportMapping":{"type":"object","properties":{"dateColumn":{"type":"string"},"amountColumn":{"type":"string"},"payeeColumn":{"type":"string"},"noteColumn":{"type":"string"},"categoryColumn":{"type":"string"},"accountColumn":{"type":"string"},"tagsColumn":{"type":"string"},"dateFormat":{"type":"string","enum":["iso","dmy","mdy"]},"numberFormat":{"type":"string","enum":["dot","comma"]}},"required":["dateColumn","amountColumn","dateFormat","numberFormat"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["System"],"summary":"Service health","responses":{"200":{"description":"The API process can accept requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/me":{"get":{"tags":["Account"],"summary":"Current user and workspaces","description":"Requires the Better Auth session cookie issued by /api/auth.","responses":{"200":{"description":"The signed-in user and the spaces they belong to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"No active session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Account"],"summary":"Delete my account and owned spaces","description":"Session cookie only: API keys and OAuth (MCP) tokens get 403 account_deletion_session_only. Re-checks the password (400 account_deletion_password). Deletes every space the user owns (expenses, invoices, learned sellers, receipts in R2, API keys), API keys the user created in other spaces, OAuth grants, sessions and the user. Memberships in other people's spaces are removed; those spaces and their expenses stay. Cannot be undone. Clears the session cookie.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletion"}}}},"responses":{"200":{"description":"The account is gone and the session cookie is cleared.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"account_deletion_password: the password is not correct. invalid_request: no password sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No active session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account_deletion_session_only: sent with an API key or OAuth token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: too many attempts from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hints":{"get":{"tags":["System"],"summary":"Sign-up suggestions","description":"Public. Prefill hints for the sign-up form: a country from the request's IP geolocation and a locale from Accept-Language. Sent with cache-control: private, no-store. Rate-limited per client address.","responses":{"200":{"description":"Suggested country and locale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hints"}}}},"429":{"description":"rate_limited: too many requests from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces":{"post":{"tags":["Workspaces"],"summary":"Create a workspace","description":"The free plan includes one owned space. Creating another returns 403 with code SPACE_LIMIT_REACHED. Spaces you were invited to do not count.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"baseCurrency":{"type":"string","description":"ISO 4217 code. Defaults to EUR when omitted."}},"required":["name"]}}}},"responses":{"200":{"description":"The new workspace id.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"SPACE_LIMIT_REACHED: the free plan includes one space. session_required: API keys cannot create workspaces.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}":{"patch":{"tags":["Workspaces"],"summary":"Update workspace settings","description":"Change the name (trimmed, 2 to 80 characters) and/or the base currency (active ISO 4217 code). Owners and admins only; other members get 403, non-members 404. Requires a signed-in session. Existing expenses keep their stored amount and currency; the new base currency applies to expenses recorded afterwards, and reports total only expenses in the base currency. Each change writes a workspace.updated audit entry with before and after values.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUpdate"}}}},"responses":{"200":{"description":"The workspace after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSettings"}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden: only an owner or admin can change settings. session_required: API keys cannot change settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/accounts":{"get":{"tags":["Accounts"],"summary":"List payment accounts","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"Accounts in the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["cash","checking","savings","credit","wallet","other"]},"currency":{"type":"string"},"archived":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","type","currency","archived","createdAt","updatedAt"]}}},"required":["accounts"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Accounts"],"summary":"Create a payment account","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["cash","checking","savings","credit","wallet","other"]},"currency":{"type":"string"}},"required":["name","type"]}}}},"responses":{"200":{"description":"The created account.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["cash","checking","savings","credit","wallet","other"]},"currency":{"type":"string"},"archived":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","type","currency","archived","createdAt","updatedAt"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/accounts/{accountId}":{"patch":{"tags":["Accounts"],"summary":"Update a payment account","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"accountId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["cash","checking","savings","credit","wallet","other"]},"archived":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated account.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["cash","checking","savings","credit","wallet","other"]},"currency":{"type":"string"},"archived":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","type","currency","archived","createdAt","updatedAt"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/categories":{"get":{"tags":["Categories"],"summary":"List categories","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"Categories, including subcategories.","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"type":"string","nullable":true},"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"sortOrder":{"type":"number"},"archived":{"type":"boolean"}},"required":["id","parentId","name","icon","color","sortOrder","archived"]}}},"required":["categories"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Categories"],"summary":"Create a category","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"parentId":{"type":"string","nullable":true},"archived":{"type":"boolean"},"sortOrder":{"type":"integer"}},"required":["name","icon","color"]}}}},"responses":{"200":{"description":"The created category.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"type":"string","nullable":true},"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"sortOrder":{"type":"number"},"archived":{"type":"boolean"}},"required":["id","parentId","name","icon","color","sortOrder","archived"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/categories/{categoryId}":{"patch":{"tags":["Categories"],"summary":"Update or archive a category","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"categoryId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"parentId":{"type":"string","nullable":true},"archived":{"type":"boolean"},"sortOrder":{"type":"integer"}}}}}},"responses":{"200":{"description":"The updated category.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"type":"string","nullable":true},"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"sortOrder":{"type":"number"},"archived":{"type":"boolean"}},"required":["id","parentId","name","icon","color","sortOrder","archived"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/tags":{"get":{"tags":["Tags"],"summary":"List tags","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"responses":{"200":{"description":"Tags in the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","createdAt"]}}},"required":["tags"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Tags"],"summary":"Create a tag","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"The created tag.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","createdAt"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/tags/{tagId}":{"patch":{"tags":["Tags"],"summary":"Rename a tag","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"tagId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"The renamed tag.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","createdAt"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Tags"],"summary":"Delete a tag","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"tagId","in":"path"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/expenses":{"get":{"tags":["Expenses"],"summary":"Search expenses","description":"Filter by text, date range, category, tag, account, payee, seller NIF (sellerVat), and amount range. q matches payee and note, and also the seller NIF exactly when it is 9 digits. Sort and paginate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"A page of expenses.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Expense"}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["items","page","pageSize","total"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Expenses"],"summary":"Record an expense","description":"Send amountMinor and spentOn, or an invoiceQr (Portuguese AT QR payload, verbatim) whose total and date become the defaults. With invoiceQr: 400 invalid_invoice_qr, unsupported_invoice_type, cancelled_invoice, invoice_zero_total, invoice_qr_mismatch or single_currency (non-EUR space); 409 duplicate_invoice when the document is already recorded in the space. Without allowDuplicate: true, 409 POSSIBLE_DUPLICATE when an expense with the same amount, currency and date and a similar payee (normalised: case, accents, punctuation and whitespace ignored; equal, contained, token Jaccard >= 0.5 or Levenshtein similarity >= 0.8) or the same HH:MM time in both notes already exists; error.duplicates lists up to 5 of them, newest first, and nothing is written. Success is 200 with the created expense.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseWrite"}}}},"responses":{"200":{"description":"The created expense.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"duplicate_invoice: this invoice is already recorded in this space; the message names the existing expense id. POSSIBLE_DUPLICATE: this looks like an expense already in the space; error.duplicates holds up to 5 matches ({ id, date, amount, currency, payee, note, createdAt }), newest first. Nothing is written. Retry with allowDuplicate: true to save it anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExpenseConflict"}}}}}}},"/workspaces/{workspaceId}/expenses/{expenseId}":{"get":{"tags":["Expenses"],"summary":"Get an expense","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"}],"responses":{"200":{"description":"The expense.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Expenses"],"summary":"Update an expense","description":"Omitted fields stay as they are. sellerVat cannot change while an invoice is linked (400 invoice_field_locked). invoiceQr is not accepted here yet: 409 invoice_already_linked when one is linked, else 400. Saving with a sellerVat and a payee updates the learned seller mapping.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Integer minor units. Required unless invoiceQr is sent; then it defaults to the invoice gross total O (euro cents)."},"spentOn":{"type":"string","description":"YYYY-MM-DD. Required unless invoiceQr is sent; then it defaults to the invoice date F."},"categoryId":{"type":"string","nullable":true},"accountId":{"type":"string","nullable":true},"payee":{"type":"string","nullable":true},"note":{"type":"string","nullable":true,"description":"Free text. With invoiceQr and no note in the body, the invoice's document id G is used."},"tagIds":{"type":"array","items":{"type":"string"}},"currency":{"type":"string"},"sellerVat":{"type":"string","nullable":true,"maxLength":20,"description":"Seller's Portuguese NIF. Spaces, dots, dashes and a \"PT\" prefix are stripped; it must be a valid 9-digit NIF other than 999999990 (invalid_nif). Null clears it. With invoiceQr it must equal QR field A (invoice_qr_mismatch); on an expense with an invoice it cannot change (invoice_field_locked). Saving with a sellerVat and a payee updates the space's learned seller mapping.","example":"123456789"},"invoiceQr":{"type":"string","maxLength":1024,"description":"Create only. The exact text inside a Portuguese invoice QR code (starts with \"A:\"), passed verbatim. The server parses it again, refuses credit notes, receipts, working and transport documents and cancelled invoices, rejects duplicates in the space (409 duplicate_invoice), and stores a snapshot (never the buyer NIF or the raw text). Amounts are euros, so the space must be EUR (single_currency). On PATCH: 409 invoice_already_linked if one is linked, else 400 (attach is not available yet)."},"invoiceSource":{"type":"string","enum":["camera","photo","text"],"description":"How invoiceQr was read: camera, photo or text. Stored on the invoice snapshot; defaults to \"api\"."},"allowDuplicate":{"type":"boolean","description":"Create only (ignored on PATCH). Default false. When the expense looks like one already in the space (same amount, currency and date, and a similar payee or the same HH:MM time in both notes), the create fails with 409 POSSIBLE_DUPLICATE and nothing is written. Send true to save it anyway."}}}}}},"responses":{"200":{"description":"The updated expense.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"invoice_already_linked: this expense already has an invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Expenses"],"summary":"Delete an expense","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/invoice-qr/preview":{"post":{"tags":["Expenses"],"summary":"Preview a Portuguese invoice QR code","description":"Read-only (scope read). Parses the QR payload on the server and returns the invoice, the proposed expense (amount O, date F, note G, seller NIF A, and O − P when there is withholding), parser warnings, the existing expense when the document is already recorded in this space, and a payee suggestion: the space's learned mapping for the seller NIF, else the EU VIES registered name for company NIFs (first digit 5, 6 or 9; only when FEATURE_VIES_LOOKUP is on), else null. VIES failures never fail the preview. Refused documents return the same 400 errors as recording an expense.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceQrPreviewRequest"}}}},"responses":{"200":{"description":"What would be recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceQrPreview"}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/expenses/{expenseId}/receipts":{"post":{"tags":["Expenses"],"summary":"Upload a receipt","description":"Multipart form with a file field. PNG, JPEG, WebP, or PDF up to 5 MB. Stored in R2.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"}],"responses":{"200":{"description":"The stored receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"byteSize":{"type":"number"}},"required":["id","filename","contentType","byteSize"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/expenses/{expenseId}/receipts/{receiptId}":{"get":{"tags":["Expenses"],"summary":"Download a receipt","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"receiptId","in":"path"}],"responses":{"200":{"description":"The receipt bytes."},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Expenses"],"summary":"Delete a receipt","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expenseId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"receiptId","in":"path"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/reports/dashboard":{"get":{"tags":["Reports"],"summary":"Dashboard figures","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"Month, trend, and recent expenses.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"otherCurrencies":{"$ref":"#/components/schemas/OtherCurrencyTotals"}},"required":["currency","otherCurrencies"],"additionalProperties":{"nullable":true}}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/reports/summary":{"get":{"tags":["Reports"],"summary":"Spending report","description":"Group a date range by category, tag, account, payee, or month, and compare with the previous period.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"Grouped totals and the previous period.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"otherCurrencies":{"$ref":"#/components/schemas/OtherCurrencyTotals"}},"required":["currency","otherCurrencies"],"additionalProperties":{"nullable":true}}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/exports/expenses.csv":{"get":{"tags":["Reports"],"summary":"Export expenses as CSV","description":"Header row in the caller's saved language: pt-PT (default) data, montante, moeda, categoria, conta, beneficiário, nota, etiquetas, NIF do vendedor, N.º do documento, ATCUD; en date, amount, currency, category, account, payee, note, tags, seller_vat, invoice_doc_id, invoice_atcud. Both import back (the last three columns are ignored on import).","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"CSV of the filtered expenses."},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/exports/report.pdf":{"get":{"tags":["Reports"],"summary":"Download a PDF report","description":"Headings and labels in the caller's saved language (pt-PT by default, or en). Category and other names are shown as stored.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tagId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"payee","in":"query"},{"schema":{"type":"string","description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits."},"required":false,"description":"Expenses: exact seller NIF (spaces, dots, dashes and a PT prefix are ignored). 400 invalid_nif when it is not 9 digits.","name":"sellerVat","in":"query"},{"schema":{"type":"string"},"required":false,"name":"minMinor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"maxMinor","in":"query"},{"schema":{"type":"string","enum":["date","amount","payee","created"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeArchived","in":"query"},{"schema":{"type":"string"},"required":false,"name":"asOf","in":"query"},{"schema":{"type":"string","enum":["category","tag","account","payee","month"]},"required":false,"name":"groupBy","in":"query"}],"responses":{"200":{"description":"A text report as a PDF."},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/imports/preview":{"post":{"tags":["Imports"],"summary":"Preview a CSV import","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"mapping":{"$ref":"#/components/schemas/ImportMapping"}},"required":["csv"]}}}},"responses":{"200":{"description":"Parsed rows, duplicates, and a suggested mapping.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"nullable":true}}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/imports":{"post":{"tags":["Imports"],"summary":"Import a CSV","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"filename":{"type":"string"},"mapping":{"$ref":"#/components/schemas/ImportMapping"},"skipDuplicates":{"type":"boolean"},"defaultCategoryId":{"type":"string","nullable":true}},"required":["csv","filename","mapping"]}}}},"responses":{"200":{"description":"How many rows were inserted, skipped, or invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"inserted":{"type":"number"},"skipped":{"type":"number"},"invalid":{"type":"number"}},"required":["importId","inserted","skipped","invalid"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Imports"],"summary":"List imports","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"responses":{"200":{"description":"Recent imports.","content":{"application/json":{"schema":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{"nullable":true}}}},"required":["imports"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/imports/{importId}/undo":{"post":{"tags":["Imports"],"summary":"Undo an import","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"importId","in":"path"}],"responses":{"200":{"description":"Expenses removed with that import id.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"number"}},"required":["removed"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/import-mappings":{"get":{"tags":["Imports"],"summary":"List saved CSV mappings","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"responses":{"200":{"description":"Saved mappings.","content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mapping":{"$ref":"#/components/schemas/ImportMapping"}},"required":["id","name","mapping"]}}},"required":["mappings"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Imports"],"summary":"Save a CSV mapping","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"mapping":{"$ref":"#/components/schemas/ImportMapping"}},"required":["name","mapping"]}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mapping":{"$ref":"#/components/schemas/ImportMapping"}},"required":["id","name","mapping"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/import-mappings/{mappingId}":{"delete":{"tags":["Imports"],"summary":"Delete a saved mapping","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"mappingId","in":"path"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/api-keys":{"get":{"tags":["API keys"],"summary":"List API keys","description":"Session only. The secret is never returned again.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"responses":{"200":{"description":"Keys for this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"lastUsedAt":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"revokedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","name","prefix","scopes","lastUsedAt","expiresAt","revokedAt","createdAt"]}}},"required":["keys"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["API keys"],"summary":"Create an API key","description":"The token is returned once. Only its hash is stored.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]},"minItems":1}},"required":["name","scopes"]}}}},"responses":{"200":{"description":"The new key, including the secret.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"lastUsedAt":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"revokedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"token":{"type":"string"}},"required":["id","name","prefix","scopes","lastUsedAt","expiresAt","revokedAt","createdAt","token"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/api-keys/{keyId}/revoke":{"post":{"tags":["API keys"],"summary":"Revoke an API key","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"The revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"lastUsedAt":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"revokedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","name","prefix","scopes","lastUsedAt","expiresAt","revokedAt","createdAt"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/budgets":{"get":{"tags":["Budgets"],"summary":"List budgets","description":"Read-only. Creating budgets is not part of this release.","parameters":[{"schema":{"type":"string"},"required":true,"name":"workspaceId","in":"path"}],"responses":{"200":{"description":"Budget rows already stored for the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"budgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"categoryId":{"type":"string","nullable":true},"categoryName":{"type":"string","nullable":true},"amountMinor":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"startsOn":{"type":"string"},"endsOn":{"type":"string","nullable":true}},"required":["id","name","categoryId","categoryName","amountMinor","currency","period","startsOn","endsOn"]}}},"required":["budgets"]}}}},"400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in, or send a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential does not allow this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing in this workspace matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}