{"components":{"schemas":{"Document":{"properties":{"amountCents":{"type":["integer","null"]},"contentType":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"documentDate":{"format":"date","type":["string","null"]},"documentType":{"enum":["invoice","receipt","credit_note","contract","bank_statement","multi_receipt_pdf","reisekostenabrechnung","bewirtungsbeleg","other"],"type":"string"},"fileName":{"type":"string"},"fileSizeBytes":{"type":["integer","null"]},"fileUrl":{"type":"string"},"id":{"type":"string"},"organizationId":{"format":"uuid","type":["string","null"]},"source":{"enum":["gmail","imap","stripe","moco","mollie","shopify","tesla","microsoft","eigenbeleg","upload","telegram","bewirtung","browser","email_export","lexware","reconciliation","other"],"type":"string"},"sourceKind":{"enum":["invoice_document","document_extraction","business_meal_document"],"type":"string"},"status":{"enum":["matched","unmatched","extracting","failed"],"type":"string"},"summary":{"type":["string","null"]},"transactionId":{"format":"uuid","type":["string","null"]},"vendor":{"type":["string","null"]}},"required":["id","sourceKind","source","fileName","contentType","currency","documentType","status","createdAt","fileUrl"],"type":"object"},"DocumentEnvelope":{"properties":{"data":{"$ref":"#/components/schemas/Document"}},"required":["data"],"type":"object"},"DocumentListEnvelope":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Document"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"type":"object"},"ErrorEnvelope":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"MeEnvelope":{"properties":{"data":{"properties":{"companyName":{"type":["string","null"]},"email":{"type":"string"},"firstname":{"type":["string","null"]},"id":{"format":"uuid","type":"string"},"lastname":{"type":["string","null"]},"organizations":{"items":{"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"parentOrganizationId":{"format":"uuid","type":["string","null"]}},"required":["id","name"],"type":"object"},"type":"array"},"token":{"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"scope":{"type":"string"}},"required":["id","name","scope"],"type":"object"}},"required":["id","email","token","organizations"],"type":"object"}},"required":["data"],"type":"object"},"Pagination":{"properties":{"hasMore":{"type":"boolean"},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total","hasMore"],"type":"object"},"Transaction":{"properties":{"amountCents":{"type":"integer"},"bankAccount":{"type":["string","null"]},"bankAccountId":{"format":"uuid","type":["string","null"]},"bookingDate":{"format":"date","type":["string","null"]},"counterparty":{"type":["string","null"]},"createdAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"description":{"type":"string"},"documents":{"items":{"$ref":"#/components/schemas/Document"},"type":"array"},"iban":{"type":["string","null"]},"id":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":["string","null"]},"reference":{"type":["string","null"]},"status":{"enum":["unprocessed","agent_running","agent_failed","waiting_for_user","waiting_for_provider","invoice_found","ignored"],"type":"string"},"statusNote":{"type":["string","null"]},"transactionDate":{"format":"date","type":"string"},"transactionType":{"type":["string","null"]},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","transactionDate","amountCents","currency","description","status","createdAt","updatedAt"],"type":"object"},"TransactionChangesEnvelope":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"sync":{"properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"since":{"format":"date-time","type":"string"},"watermark":{"format":"date-time","type":"string"}},"required":["since","watermark","nextCursor","hasMore"],"type":"object"}},"required":["data","sync"],"type":"object"},"TransactionEnvelope":{"properties":{"data":{"$ref":"#/components/schemas/Transaction"}},"required":["data"],"type":"object"},"TransactionListEnvelope":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"type":"object"},"UploadDocumentEnvelope":{"properties":{"data":{"properties":{"contentType":{"type":"string"},"fileName":{"type":"string"},"fileSizeBytes":{"type":["integer","null"]},"fileUrl":{"type":"string"},"id":{"type":"string"},"organizationId":{"format":"uuid","type":["string","null"]},"queued":{"type":"boolean"},"sourceKind":{"enum":["document_extraction"],"type":"string"},"status":{"type":"string"},"transactionId":{"format":"uuid","type":["string","null"]}},"required":["id","sourceKind","fileName","contentType","status","queued","fileUrl"],"type":"object"}},"required":["data"],"type":"object"}},"securitySchemes":{"bearerAuth":{"scheme":"bearer","type":"http"}}},"info":{"description":"Stable ingest and read API for belege.ai documents and transactions.","title":"belege.ai Public API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/documents":{"get":{"parameters":[{"description":"Page size.","in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Zero-based offset.","in":"query","name":"offset","required":false,"schema":{"type":"integer"}},{"description":"Filter by a visible organization UUID.","in":"query","name":"organizationId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Filter by a visible transaction UUID.","in":"query","name":"transactionId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Search filename, vendor, or summary.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Comma-separated document sources.","in":"query","name":"source","required":false,"schema":{"description":"Comma-separated values from: gmail, imap, stripe, moco, mollie, shopify, tesla, microsoft, eigenbeleg, upload, telegram, bewirtung, browser, email_export, lexware, reconciliation, other","type":"string"}},{"description":"Comma-separated document types.","in":"query","name":"type","required":false,"schema":{"description":"Comma-separated values from: invoice, receipt, credit_note, contract, bank_statement, multi_receipt_pdf, reisekostenabrechnung, bewirtungsbeleg, other","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListEnvelope"}}},"description":"Document list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"List visible documents"},"post":{"parameters":[],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"PDF, JPG, JPEG, or PNG up to 128 MB.","format":"binary","type":"string"},"note":{"type":"string"},"organizationId":{"format":"uuid","type":"string"},"transactionId":{"format":"uuid","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadDocumentEnvelope"}}},"description":"Uploaded document extraction"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"File too large"}},"summary":"Upload a document"}},"/api/v1/documents/{documentId}":{"get":{"parameters":[{"description":"Prefixed document id.","in":"path","name":"documentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentEnvelope"}}},"description":"Document"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"Get one visible document"}},"/api/v1/documents/{documentId}/file":{"get":{"parameters":[{"description":"Prefixed document id.","in":"path","name":"documentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}},"application/pdf":{"schema":{"format":"binary","type":"string"}},"image/jpeg":{"schema":{"format":"binary","type":"string"}},"image/png":{"schema":{"format":"binary","type":"string"}}},"description":"Document bytes"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"Download document bytes"}},"/api/v1/me":{"get":{"parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeEnvelope"}}},"description":"Current user and token"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"Current API principal"}},"/api/v1/openapi.json":{"get":{"parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI document"}},"security":[],"summary":"OpenAPI schema"}},"/api/v1/transactions":{"get":{"parameters":[{"description":"Page size.","in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Zero-based offset.","in":"query","name":"offset","required":false,"schema":{"type":"integer"}},{"description":"Filter by a visible organization UUID.","in":"query","name":"organizationId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Search description, counterparty, or reference.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Inclusive transaction date lower bound.","in":"query","name":"from","required":false,"schema":{"format":"date","type":"string"}},{"description":"Inclusive transaction date upper bound.","in":"query","name":"to","required":false,"schema":{"format":"date","type":"string"}},{"description":"Comma-separated transaction statuses.","in":"query","name":"status","required":false,"schema":{"description":"Comma-separated values from: unprocessed, agent_running, agent_failed, waiting_for_user, waiting_for_provider, invoice_found, ignored","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionListEnvelope"}}},"description":"Transaction list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"List visible transactions"}},"/api/v1/transactions/changes":{"get":{"parameters":[{"description":"Required on the first page. Return transactions updated strictly after this RFC 3339 timestamp.","in":"query","name":"since","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Opaque nextCursor from the preceding page. Omit since when continuing.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Page size. Defaults to 200.","in":"query","name":"limit","required":false,"schema":{"default":200,"maximum":200,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionChangesEnvelope"}}},"description":"Stable transaction change page"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"Synchronize transaction changes"}},"/api/v1/transactions/{transactionId}":{"get":{"parameters":[{"description":"Transaction UUID.","in":"path","name":"transactionId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}},"description":"Transaction with matching documents"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid bearer token"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"}},"summary":"Get one visible transaction"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://belege.ai"}]}