{"note":"OpenAPI conversion -- returning structured metadata","name":"xero-com-xero-files","description":"Xero Files API","version":"12.0.0","base_url":"https://api.xero.com/files.xro/1.0/","endpoints":18,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Xero Files API\n@base https://api.xero.com/files.xro/1.0/\n@version 12.0.0\n@auth OAuth2\n@endpoints 18\n@toc Files(10), Associations(2), Folders(5), Inbox(1)\n\n@group Files\n@endpoint GET /Files\n@desc Retrieves files\n@optional {pagesize: int # pass an optional page size value, page: int # number of records to skip for pagination, sort: str(Name/Size/CreatedDateUTC) # values to sort by, direction: str(ASC/DESC) # sort direction}\n@returns(200) {TotalCount: int, Page: int, PerPage: int, Items: [map]} # search results matching criteria\n\n@endpoint POST /Files\n@desc Uploads a File to the inbox\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max.}\n@returns(201) {Name: str, MimeType: str, Size: int, CreatedDateUtc: str, UpdatedDateUtc: str, User: map{Id: str(uuid), Name: str, FirstName: str, LastName: str, FullName: str}, Id: str(uuid), FolderId: str(uuid)} # A successful request\n@errors {400: invalid input, object invalid}\n\n@endpoint GET /Files/{FileId}\n@desc Retrieves a file by a unique file ID\n@required {FileId: str(uuid) # File id for single object}\n@returns(200) {Name: str, MimeType: str, Size: int, CreatedDateUtc: str, UpdatedDateUtc: str, User: map{Id: str(uuid), Name: str, FirstName: str, LastName: str, FullName: str}, Id: str(uuid), FolderId: str(uuid)} # search results matching criteria\n\n@endpoint PUT /Files/{FileId}\n@desc Update a file\n@required {FileId: str(uuid) # File id for single object}\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max., Name: str # File Name, MimeType: str # MimeType of the file (image/png, image/jpeg, application/pdf, etc..), Size: int # Numeric value in bytes, CreatedDateUtc: str # Created date in UTC, UpdatedDateUtc: str # Updated date in UTC, User: map{Id!: str(uuid), Name: str, FirstName: str, LastName: str, FullName: str}, Id: str(uuid) # File object's UUID, FolderId: str(uuid) # Folder relation object's UUID}\n@returns(200) {Name: str, MimeType: str, Size: int, CreatedDateUtc: str, UpdatedDateUtc: str, User: map{Id: str(uuid), Name: str, FirstName: str, LastName: str, FullName: str}, Id: str(uuid), FolderId: str(uuid)} # A successful request\n@errors {400: invalid input, object invalid}\n@example_request \"{ \\\"FolderId\\\": \\\"bf924975-7097-46f2-a143-1ecfbab3c8c3\\\" }\"\n\n@endpoint DELETE /Files/{FileId}\n@desc Deletes a specific file\n@required {FileId: str(uuid) # File id for single object}\n@returns(204) Successful deletion - return response 204 no content\n\n@endpoint POST /Files/{FolderId}\n@desc Uploads a File to a specific folder\n@required {FolderId: str(uuid) # pass required folder id to save file to specific folder}\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max.}\n@returns(201) {Name: str, MimeType: str, Size: int, CreatedDateUtc: str, UpdatedDateUtc: str, User: map{Id: str(uuid), Name: str, FirstName: str, LastName: str, FullName: str}, Id: str(uuid), FolderId: str(uuid)} # A successful request\n@errors {400: invalid input, object invalid}\n\n@endpoint GET /Files/{FileId}/Content\n@desc Retrieves the content of a specific file\n@required {FileId: str(uuid) # File id for single object}\n@returns(200) returns the byte array of the specific file based on id\n\n@endpoint GET /Files/{FileId}/Associations\n@desc Retrieves a specific file associations\n@required {FileId: str(uuid) # File id for single object}\n@returns(200) search results matching criteria\n\n@endpoint POST /Files/{FileId}/Associations\n@desc Creates a new file association\n@required {FileId: str(uuid) # File id for single object}\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max., SendWithObject: bool # Boolean flag to determines whether the file is sent with the document it is attached to on client facing communications. Note- The SendWithObject element is only returned when using /Associations/{ObjectId} endpoint., Name: str # The name of the associated file. Note- The Name element is only returned when using /Associations/{ObjectId} endpoint., Size: int # The size of the associated file in bytes. Note- The Size element is only returned when using /Associations/{ObjectId} endpoint., FileId: str(uuid) # The unique identifier of the file, ObjectId: str(uuid) # The identifier of the object that the file is being associated with (e.g. InvoiceID, BankTransactionID, ContactID), ObjectGroup: str(Account/BankTransaction/Contact/CreditNote/Invoice/Item/ManualJournal/Overpayment/Payment/Prepayment/Quote/Receipt) # The Object Group that the object is in. These roughly correlate to the endpoints that can be used to retrieve the object via the core accounting API., ObjectType: str(Unknown/Accpay/AccPayCredit/AccPayPayment/AccRec/AccRecCredit/AccRecPayment/Adjustment/ApCreditPayment/ApOverPayment/ApOverPaymentPayment/ApOverPaymentSourcePayment/ApPrepayment/ApPrepaymentPayment/ApPrepaymentSourcePayment/ArCreditPayment/ArOverPayment/ArOverpaymentPayment/ArOverpaymentSourcePayment/ArPrepayment/ArPrepaymentPayment/ArPrepaymentSourcePayment/CashPaid/CashRec/ExpPayment/ManJournal/PurchaseOrder/Receipt/Transfer/Account/Contact/Business/Employee/Person/User/Org/FixedAsset/PayRun/PriceListItem/Bank/Current/Equity/Expense/Fixed/Liability/Prepayment/Revenue/Sales/Overheads/Depreciatn/OtherIncome/DirectCosts/Currliab/Termliab/NonCurrent/SalesQuote) # The Object Type}\n@returns(201) {SendWithObject: bool, Name: str, Size: int, FileId: str(uuid), ObjectId: str(uuid), ObjectGroup: str, ObjectType: str} # A successful request\n@errors {400: invalid input, object invalid}\n@example_request \"{ \\\"ObjectId\\\": \\\"1270bf7c-5d18-473a-9231-1e36c4bd33ed\\\", \\\"ObjectGroup\\\": \\\"Contact\\\", \\\"ObjectType\\\": \\\"Business\\\" }\"\n\n@endpoint DELETE /Files/{FileId}/Associations/{ObjectId}\n@desc Deletes an existing file association\n@required {FileId: str(uuid) # File id for single object, ObjectId: str(uuid) # Object id for single object}\n@returns(204) Successful deletion - return response 204 no content\n\n@endgroup\n\n@group Associations\n@endpoint GET /Associations/{ObjectId}\n@desc Retrieves an association object using a unique object ID\n@required {ObjectId: str(uuid) # Object id for single object}\n@optional {pagesize: int # pass an optional page size value, page: int # number of records to skip for pagination, sort: str(Name/CreatedDateUTC) # values to sort by, direction: str(ASC/DESC) # direction to sort by}\n@returns(200) search results matching criteria\n\n@endpoint GET /Associations/Count\n@desc Retrieves a count of associations for a list of objects.\n@required {ObjectIds: [str(uuid)] # A comma-separated list of object ids}\n@returns(200) A dictionary of the object Ids and associations count\n\n@endgroup\n\n@group Folders\n@endpoint GET /Folders\n@desc Retrieves folders\n@optional {sort: str(Name/Size/CreatedDateUTC) # values to sort by}\n@returns(200) search results matching criteria\n\n@endpoint POST /Folders\n@desc Creates a new folder\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max., Name: str # The name of the folder, FileCount: int # The number of files in the folder, Email: str # The email address used to email files to the inbox. Only the inbox will have this element., IsInbox: bool # to indicate if the folder is the Inbox. The Inbox cannot be renamed or deleted., Id: str(uuid) # Xero unique identifier for a folder  Files}\n@returns(200) {Name: str, FileCount: int, Email: str, IsInbox: bool, Id: str(uuid)} # search results matching criteria\n@errors {400: invalid input, object invalid}\n@example_request \"{ \\\"Name\\\": \\\"My Docs\\\" }\"\n\n@endpoint GET /Folders/{FolderId}\n@desc Retrieves specific folder by using a unique folder ID\n@required {FolderId: str(uuid) # Folder id for single object}\n@returns(200) {Name: str, FileCount: int, Email: str, IsInbox: bool, Id: str(uuid)} # search results matching criteria\n\n@endpoint PUT /Folders/{FolderId}\n@desc Updates an existing folder\n@required {FolderId: str(uuid) # Folder id for single object}\n@optional {Idempotency-Key: str # This allows you to safely retry requests without the risk of duplicate processing. 128 character max., Name: str # The name of the folder, FileCount: int # The number of files in the folder, Email: str # The email address used to email files to the inbox. Only the inbox will have this element., IsInbox: bool # to indicate if the folder is the Inbox. The Inbox cannot be renamed or deleted., Id: str(uuid) # Xero unique identifier for a folder  Files}\n@returns(200) {Name: str, FileCount: int, Email: str, IsInbox: bool, Id: str(uuid)} # return the updated object\n@errors {400: invalid input, object invalid}\n@example_request \"{ \\\"Name\\\": \\\"Your Docs\\\" }\"\n\n@endpoint DELETE /Folders/{FolderId}\n@desc Deletes a folder\n@required {FolderId: str(uuid) # Folder id for single object}\n@returns(204) Successful deletion - return response 204 no content\n\n@endgroup\n\n@group Inbox\n@endpoint GET /Inbox\n@desc Retrieves inbox folder\n@returns(200) {Name: str, FileCount: int, Email: str, IsInbox: bool, Id: str(uuid)} # search results matching criteria\n\n@endgroup\n\n@end\n"}