{"openapi":"3.0.0","info":{"title":"File Operations","description":"The official SeaTable API Reference (OpenAPI 3.0).","version":"6.1"},"servers":[{"url":"https://{server}","variables":{"server":{"default":"cloud.seatable.io"}}}],"x-readme":{"explorer-enabled":true,"metrics-enabled":false,"proxy-enabled":false},"tags":[{"name":"Files & Images","description":"Manage file and image attachments within a base"},{"name":"Files & Images (Custom Folder)","description":"Manage file and image attachments stored within custom folders"}],"components":{"securitySchemes":{"ApiTokenAuth":{"type":"http","scheme":"bearer","description":"This is the [API-Token](/reference/authentication)."}},"parameters":{"file_path":{"name":"path","in":"query","schema":{"type":"string","pattern":"^\\/(images|files){1}\\/[0-9]{4}\\-[0-9]{2}\\/."},"description":"Path to the file","example":"/images/2021-03/test.png","required":true},"upload_link":{"name":"upload_link","description":"This is the value you got from the call Get File/Image Upload Link via API Token.","in":"path","schema":{"type":"string","pattern":"^[a-z0-9]{8}(-[a-z0-9]{4}){3}-[a-z0-9]{12}$"},"required":true,"example":"5e666848-4152-45e5-990e-d686960f2a05"},"custom_folder_path":{"name":"path","in":"query","schema":{"type":"string"},"description":"Path of the custom folder","example":"/","required":true},"custom_folder_file_name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Name of the file in the custom folder","example":"b374.pdf","required":true},"custom_folder_path_with_filename":{"name":"path","in":"query","schema":{"type":"string"},"description":"Path and name of the file in the custom folder","example":"/supplierOne/b374.pdf","required":true}},"schemas":{"upload_file_image":{"type":"object","properties":{"file":{"type":"string","description":"The file or image you'd like to upload from your local drive.","format":"binary"},"parent_dir":{"type":"string","description":"This is the value of the `parent_path` you got from the call **Get File/Image Upload Link via API Token**.","example":"/asset/a275d870-fd55-48e4-8c4a-5fd6f2549765"},"replace":{"type":"string","enum":["0","1"],"description":"Do you want to overwrite a file/image with the same name? `0` - No, `1` - Yes. Optional. `0` by default. If existing file is not overwritten, the uploaded file will be renamed as `filename(1).xxx`.","example":"0"},"relative_path":{"type":"string","description":"If you are uploading a file, use the value of the `file_relative_path` returned in the call **Get File/Image Upload Link via API Token**; or the `img_relative_path` for image.","example":"images/2021-08","pattern":"^(images|files){1}\\/[0-9]{4}\\-[0-9]{2}$"}},"required":["file","parent_dir","relative_path"]}}},"paths":{"/api/v2.1/dtable/app-upload-link/":{"get":{"tags":["Files & Images"],"summary":"Get Upload Link","operationId":"getUploadLink","description":"Generate an upload link, including the parent- and the relative path. These values are needed in order to [upload a file / an image](https://api.seatable.com/reference/uploadfile) to a base.\nAfterwards, this file/image can be attached to a file/image column. Please note that this endpoint requires an **API token** instead of a **Base token**.\n\n> 📘 The upload link is only valid for a short time\n> \n> The upload link is only valid for some minutes. After that the upload link must be created again.\n","security":[{"ApiTokenAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"upload_link":{"type":"string"},"workspace_id":{"type":"integer"},"parent_path":{"type":"string"},"img_relative_path":{"type":"string"},"file_relative_path":{"type":"string"}}},"example":{"upload_link":"https://cloud.seatable.io/seafhttp/upload-api/83e701c8-84ba-498c-91b1-ddb3789edb7e","workspace_id":42,"parent_path":"/asset/a275d870-fd55-48e4-8c4a-5fd6f2549765","img_relative_path":"images/2021-08","file_relative_path":"files/2021-08"}}}}}}},"/seafhttp/upload-api/{upload_link}?ret-json=1":{"post":{"tags":["Files & Images"],"summary":"Upload File (or Image)","operationId":"uploadFile","description":"Upload a file or an image as an attachment to a base. To execute this request you need to generate an upload link first. \n\n> 📘 Three steps to add a file/an image to a base\n> \n> To add an image or a file to a base, three steps are necessary: \n> 1. [Generate an upload link](/reference/getuploadlink).\n> 2. Upload the file to the base as an attachment. (this article)\n> 3. [Update a row](/reference/updaterow) and attach the file/the image to a file or image column. \n>\n> The [SeaTable Developer Manual](https://developer.seatable.com/clients/javascript/examples/file-upload/) includes a Node.js script that showcases the necessary API calls.\n\n> 📘 Different variable names\n> \n> Pay attention that the return values of upload link have slightly different names, so `parent_path` is `parent_dir` in this call.\n\n## Attach the file/image to a file or image column\n\nAfter uploading the file/image to a base, SeaTable saves the uploaded file at non-public URL in the form: `/workspace/{workspace_id}`+`parent_dir`+`relative_path`+`name`.\nYou are expected to construct this relative URL yourself.\n\nThe URL consists of the following components:\n- `workspace_id`: Each base is attached to a workspace. You can use the [Get Base-Token with API-Token](https://api.seatable.com/reference/getbasetokenwithapitoken) endpoint to retrieve the workspace ID for a base.\n- `parent_dir`: Use the value of the `parent_path` field from the response of the [Get Upload Link](https://api.seatable.com/reference/getuploadlink) API call.\n- `relative_path`: Use the value of the `img_relative_path` or `file_relative_path` field (depending on the type of asset you want to upload) from the response of the [Get Upload Link](https://api.seatable.com/reference/getuploadlink) API call.\n- `name`: Use the value of the `name` field from the response of the [Upload File (or Image)](https://api.seatable.com/reference/uploadfile) API call.\n\nHere is an example how this might look like: `https://cloud.seatable.io/workspace/24/asset/55f2f056-5da1-4095-b5f8-791bb51b991e/images/2023-07/party.png`\nIf you are logged in with your browser, you can access this file. Otherwise you will see the login screen.\n\nKnowing this URL, you can add a new row or update an existing row and use the URL to add this attachment to your file/image column.\n```\n# Example how to add an already uploaded image to a row:\n\"row\": {\n  \"My Image Column\": [\"/workspace/24/asset/55f2f056-5da1-4095-b5f8-791bb51b991e/images/2023-07/party.png\"]\n}\n\n# Example how to add an already uploaded file to a row:\n\"row\": {\n  \"File Column\": [{\n    \"name\": \"invoice.pdf\", \n    \"size\": 101454, \n    \"type\": \"file\", \n    \"url\": \"/workspace/24/asset/55f2f056-5da1-4095-b5f8-791bb51b991e/images/2023-07/invoice.pdf\"\n  }]\n}\n```\n> 🚧 File requires the input variables size, type and url\n> \n> As you can see, in the case of an image the URL is sufficient to attach the image to an image column. In case of a file, you have to provide all four input values.\n","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/upload_file_image"}}}},"security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/upload_link"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}},"example":[{"name":"favicon.ico","id":"b4356e3000d01a37b458524b59cecb1a5d23d964","size":67646}]}}}}}},"/api/v2.1/dtable/app-download-link/":{"get":{"tags":["Files & Images"],"summary":"Get File Download Link","operationId":"getFileDownloadLink","description":"Get the file download link of a base's attachment. \n\n> 📘 The download link is only valid for a short time\n> \n> The download link is only valid for some hours. After that the download link must be created again. We recommend\nto store images on public hosting services like AWS S3 and saving only the links in SeaTable, allowing direct use of image links in web pages.\n","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/file_path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"download_link":"https://cloud.seatable.io/seafhttp/files/12345678-1234-4672-834c-4eca40dc104b/test.png"}}}},"400":{"description":"Bad Request — file not found at the given path.","content":{"application/json":{"schema":{"type":"object","properties":{"error_msg":{"type":"string","example":"path /files/2020-01/nonexistent.txt not found."}}}}}}}}},"/api/v2.1/dtable/app-asset/":{"delete":{"tags":["Files & Images"],"summary":"Delete a Base Asset","operationId":"deleteBaseAsset","description":"Delete a base's attachment.\n","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/file_path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true}}}},"404":{"description":"Not Found — file does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error_msg":{"type":"string","example":"File not found."}}}}}}}}},"/api/v2.1/dtable/custom/app-asset-dir/":{"get":{"tags":["Files & Images (Custom Folder)"],"summary":"Get Files from Folder","operationId":"getCustomFiles","description":"List files and subdirectories in a custom folder of a base.","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/custom_folder_path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"dir":[{"name":"Invoices"},{"name":"Requests"}],"file":[{"name":"b347.pdf"}]}}}}}}},"/api/v2.1/dtable/custom/app-asset-file/":{"get":{"tags":["Files & Images (Custom Folder)"],"summary":"Get File Metadata","operationId":"getCustomFileMetadata","description":"Get metadata (name, size, last update) of a file in a custom folder.","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/custom_folder_path"},{"$ref":"#/components/parameters/custom_folder_file_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"dirent":{"is_file":true,"obj_name":"b347.pdf","file_size":11583,"last_update":"2023-04-11T14:59:53+08:00","uuid":"2bbe9499-e1df-4086-bdd3-d130d6c91bd3"}}}}}}},"delete":{"tags":["Files & Images (Custom Folder)"],"summary":"Delete a Base Asset in Custom Folder","operationId":"deleteBaseCustomFolderAsset","description":"Delete a base's attachment in custom folder.\n","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/custom_folder_path_with_filename"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true}}}}}}},"/api/v2.1/dtable/custom/app-upload-link/":{"get":{"tags":["Files & Images (Custom Folder)"],"summary":"Get Upload Link","operationId":"getCustomUploadLink","description":"Get a temporary upload link for uploading files to a custom folder.","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/custom_folder_path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"dirent":{"upload_link":"https://cloud.seatable.io/seafhttp/upload-api/e943a56a-c5b3-441a-ac1d-9199819dec71","workspace_id":42,"parent_path":"/asset/1338f224-8482-4d71-b8be-63c8f37b896a/custom","relative_path":"/"}}}}}}}},"/api/v2.1/dtable/custom/app-download-link/":{"get":{"tags":["Files & Images (Custom Folder)"],"summary":"Get Download Link","operationId":"getCustomDownloadLink","description":"Get a temporary download link for a file in a custom folder.","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/custom_folder_path_with_filename"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"dirent":{"download_link":"https://cloud.seatable.io/seafhttp/files/a73e26e9-0417-4d98-bb5d-92826f4af671/b347.pdf"}}}}}}}}}}