{"openapi":"3.1.0","info":{"title":"dir Open API","version":"1.0.0","description":"เชื่อมระบบภายนอกเข้ากับ dir — อ่าน/เขียนไฟล์ ค้นหา และนัดหมาย\n\nกุญแจสวมบทเป็นผู้ใช้คนหนึ่งเสมอ สิทธิ์ที่ได้จึงเท่ากับสิทธิ์ของคนนั้น ทุกคำขอต้องส่งส่วนหัว `Authorization: Bearer dir_<id>_<secret>`"},"servers":[{"url":"https://dir.biza.me"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"กุญแจจากหน้า API ในระบบ (ขอบเขต read หรือ write)"}},"schemas":{"Entry":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string","description":"ทางเดินเต็มในที่เก็บนั้น เริ่มด้วย /"},"isDir":{"type":"boolean"},"size":{"type":"integer","description":"ไบต์"},"mtime":{"type":"integer","description":"เวลาแก้ไขล่าสุด (epoch ms)"}}}},"responses":{"Unauthorized":{"description":"กุญแจหาย ผิด หมดอายุ หรือถูกยกเลิก"},"Forbidden":{"description":"กุญแจเป็นแบบอ่านอย่างเดียว หรือผู้ใช้ที่สวมบทไม่มีสิทธิ์ในที่นั้น"},"TooMany":{"description":"เรียกถี่เกินกำหนดต่อนาที"}}},"paths":{"/api/v1/me":{"get":{"summary":"ตรวจกุญแจ — บอกว่าสวมบทเป็นใคร ขอบเขตไหน","responses":{"200":{"description":"ข้อมูลกุญแจและผู้ใช้","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scope":{"type":"string","enum":["read","write"]}}}}}}}}}}},"/api/v1/connections":{"get":{"summary":"ที่เก็บทั้งหมดที่กุญแจนี้เข้าถึงได้","responses":{"200":{"description":"รายการที่เก็บ","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"role":{"type":"string"}}}}}}}}}}}},"/api/v1/files":{"get":{"summary":"รายการไฟล์ในโฟลเดอร์","parameters":[{"name":"connection","in":"query","required":true,"description":"id ของที่เก็บ","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"โฟลเดอร์ (ค่าเริ่มต้น /)","schema":{"type":"string"}}],"responses":{"200":{"description":"รายการไฟล์","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}}}}}}},"delete":{"summary":"ลบไฟล์/โฟลเดอร์ (ย้ายเข้าถังขยะ กู้คืนได้)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}}},"required":["connection","paths"]}}}},"responses":{"200":{"description":"ลบแล้ว","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"},"trashIds":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/v1/files/stat":{"get":{"summary":"ข้อมูลไฟล์เดียว","parameters":[{"name":"connection","in":"query","required":true,"description":"id ของที่เก็บ","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"ทางเดินของไฟล์","schema":{"type":"string"}}],"responses":{"200":{"description":"ข้อมูลไฟล์","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}}}}},"/api/v1/files/download":{"get":{"summary":"ดาวน์โหลดไฟล์ (รองรับ Range เพื่อโหลดต่อ)","parameters":[{"name":"connection","in":"query","required":true,"description":"id ของที่เก็บ","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"ทางเดินของไฟล์","schema":{"type":"string"}}],"responses":{"200":{"description":"เนื้อไฟล์","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"บางส่วนตาม Range"}}}},"/api/v1/files/upload":{"post":{"summary":"อัปโหลดไฟล์ — ส่งเนื้อไฟล์ดิบใน body พร้อม Content-Length","parameters":[{"name":"connection","in":"query","required":true,"description":"id ของที่เก็บ","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"โฟลเดอร์ปลายทาง","schema":{"type":"string"}},{"name":"name","in":"query","required":true,"description":"ชื่อไฟล์","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"เขียนแล้ว","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"}}}}}}}}},"/api/v1/folders":{"post":{"summary":"สร้างโฟลเดอร์ (ซ้อนหลายชั้นได้ด้วย dirs)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"path":{"type":"string","description":"โฟลเดอร์แม่"},"name":{"type":"string","description":"ชื่อโฟลเดอร์ใหม่ (ชั้นเดียว)"},"dirs":{"type":"array","items":{"type":"string"},"description":"หลายชั้นพร้อมกัน ใช้แทน name"}},"required":["connection","path"]}}}},"responses":{"200":{"description":"สร้างแล้ว","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"}}}}}}}}},"/api/v1/files/rename":{"post":{"summary":"เปลี่ยนชื่อ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"path":{"type":"string"},"name":{"type":"string"}},"required":["connection","path","name"]}}}},"responses":{"200":{"description":"เปลี่ยนแล้ว","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"}}}}}}}}},"/api/v1/files/move":{"post":{"summary":"ย้ายหรือคัดลอกไปโฟลเดอร์อื่น (ที่เก็บเดียวกัน)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}},"dest":{"type":"string","description":"โฟลเดอร์ปลายทาง"},"copy":{"type":"boolean","description":"true = คัดลอก (ค่าเริ่มต้นคือย้าย)"}},"required":["connection","paths","dest"]}}}},"responses":{"200":{"description":"ย้าย/คัดลอกแล้ว","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/api/v1/search":{"get":{"summary":"ค้นหาไฟล์จากชื่อ ทางเดิน และเนื้อในเอกสาร","parameters":[{"name":"q","in":"query","required":true,"description":"คำค้น อย่างน้อย 2 ตัวอักษร","schema":{"type":"string"}},{"name":"connection","in":"query","required":false,"description":"จำกัดที่เก็บเดียว","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"ชนิด: video|audio|image|doc|sheet|slide|pdf|text|archive|other","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"จำนวนสูงสุด","schema":{"type":"integer","default":60}}],"responses":{"200":{"description":"ผลค้นหา","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}}}}},"/api/v1/office/link":{"post":{"summary":"ขอลิงก์เปิดเอกสารในเบราว์เซอร์ ให้คนที่ไม่มีบัญชี dir กดได้","description":"คืนลิงก์ที่เปิดตัวแก้เอกสาร (ONLYOFFICE) ได้ทันทีโดยไม่ต้องล็อกอิน เบื้องหลังคือลิงก์แชร์จริง จึงเห็นในหน้า \"ลิงก์ที่แชร์\" ยกเลิกได้ และมีบันทึกว่าใครเปิดเมื่อไหร่\n\nลิงก์หนึ่งเส้นใช้ซ้ำได้จนหมดอายุ — ระบบภายนอกควรเก็บไว้ใช้ต่อ ไม่ใช่ขอใหม่ทุกครั้งที่ผู้ใช้กด ไม่งั้นรายการลิงก์แชร์จะเต็มไปด้วยลิงก์ที่ไม่มีใครใช้","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","description":"รหัสที่เก็บ (จาก /api/v1/connections)"},"path":{"type":"string","description":"ทางเดินเต็มของไฟล์"},"mode":{"type":"string","enum":["view","edit"],"default":"view","description":"edit ต้องใช้กุญแจขอบเขต write และผู้ใช้ต้องมีสิทธิ์เขียนไฟล์นั้น"},"expiresInMinutes":{"type":"integer","description":"อายุลิงก์เป็นนาที (ไม่ใส่ = ไม่หมดอายุ)"},"expiresInDays":{"type":"integer","description":"อายุลิงก์เป็นวัน ใช้เมื่อไม่ได้ส่ง expiresInMinutes"},"password":{"type":"string","description":"ถ้าใส่ ผู้รับต้องกรอกรหัสก่อนเปิด"},"note":{"type":"string","description":"ข้อความถึงผู้รับ"}},"required":["connection","path"]}}}},"responses":{"200":{"description":"ลิงก์ที่เปิดได้ทันที","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["view","edit"]},"name":{"type":"string"},"url":{"type":"string","description":"เปิดตัวแก้เอกสารตรง ๆ ใส่ iframe หรือเปิดแท็บใหม่ได้"},"pageUrl":{"type":"string","description":"หน้าลิงก์แชร์ปกติ มีปุ่มดาวน์โหลดด้วย"},"token":{"type":"string"},"shareId":{"type":"string","description":"ใช้กับ DELETE /api/shares/{id} เพื่อยกเลิกลิงก์"},"expiresAt":{"type":"integer","description":"epoch ms — null คือไม่หมดอายุ"}}}}}}}}},"/api/v1/shares":{"get":{"summary":"ลิงก์แชร์ทั้งหมดที่ผู้ใช้คนนี้ออกไว้ (รวมลิงก์เปิดเอกสาร)","responses":{"200":{"description":"รายการลิงก์","content":{"application/json":{"schema":{"type":"object","properties":{"shares":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/shares/{id}":{"delete":{"summary":"ลบลิงก์ที่ออกไว้ — ลิงก์ที่ส่งไปแล้วใช้ไม่ได้ทันที","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"shareId จาก /api/v1/office/link"}],"responses":{"200":{"description":"รายการลิงก์ที่เหลือ","content":{"application/json":{"schema":{"type":"object","properties":{"shares":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/office/session":{"post":{"summary":"ขอ config ไปฝังตัวแก้เอกสารในหน้าเว็บของระบบภายนอกเอง","description":"สำหรับระบบที่อยากคุมหน้าตาเอง — เอา `config` ที่ได้ไปเรียก `new DocsAPI.DocEditor(el, config)` โดยโหลดสคริปต์จาก `docsUrl`/web-apps/apps/api/documents/api.js\n\nconfig เซ็น JWT มาแล้ว แก้อะไรในนั้นไม่ได้ (document server จะปฏิเสธ) ถ้าอยากได้แค่ลิงก์กดแล้วเปิดเลย ใช้ /api/v1/office/link ง่ายกว่ามาก","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"path":{"type":"string"},"mode":{"type":"string","enum":["view","edit"],"default":"view"},"theme":{"type":"string","enum":["light","dark"],"default":"light"},"user":{"type":"object","description":"ชื่อคนที่กำลังเปิดในระบบภายนอก — โชว์เป็นป้ายชื่อตอนหลายคนแก้พร้อมกัน","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"required":["connection","path"]}}}},"responses":{"200":{"description":"config ของตัวแก้เอกสาร","content":{"application/json":{"schema":{"type":"object","properties":{"docsUrl":{"type":"string"},"config":{"type":"object","description":"ส่งให้ DocsAPI.DocEditor ทั้งก้อน"},"readOnly":{"type":"boolean","description":"true เมื่อเปิดได้แบบอ่านอย่างเดียว (โหมด view หรือมีคนล็อกไฟล์อยู่)"},"lock":{"type":"object","nullable":true,"description":"ใครล็อกไฟล์นี้อยู่"},"name":{"type":"string"}}}}}}}}},"/api/v1/calendar":{"get":{"summary":"นัดหมายที่ผู้ใช้คนนี้เห็น","responses":{"200":{"description":"นัดหมาย","content":{"application/json":{"schema":{"type":"object","properties":{"upcoming":{"type":"array","items":{"type":"object"}},"past":{"type":"array","items":{"type":"object"}}}}}}}}},"post":{"summary":"ลงนัดใหม่","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"at":{"type":"integer","description":"เวลานัด (epoch ms)"},"allDay":{"type":"boolean"},"groupId":{"type":"string","description":"ผูกกับกลุ่มไลน์ (ต้องเป็นคนเก็บของกลุ่มนั้น)"}},"required":["title","at"]}}}},"responses":{"200":{"description":"ลงนัดแล้ว","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}