{"openapi":"3.1.0","info":{"title":"mdfiles.io API","version":"0.1.0"},"servers":[{"url":"https://www.mdfiles.io"}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer"}},"schemas":{"Visibility":{"type":"string","enum":["link","private","public"],"description":"File privacy. private is owner/collaborator only; link allows anyone with the URL; public is public."},"Status":{"type":"string","enum":["in_progress","draft","review","final"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/api/v1/me":{"get":{"summary":"Verify API key","responses":{"200":{"description":"Account details"},"401":{"description":"Invalid API key"}}}},"/api/v1/files":{"get":{"summary":"List Markdown files","responses":{"200":{"description":"Owned files","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"share_id":{"type":"string"},"external_id":{"type":["string","null"]},"title":{"type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"},"status":{"$ref":"#/components/schemas/Status"},"version":{"type":"integer"},"view_url":{"type":"string","format":"uri"},"edit_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"latest_version":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"version_number":{"type":"integer"},"change_summary":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}}}}},"required":["files"]}}}},"401":{"description":"Invalid API key"}}},"post":{"summary":"Create a Markdown file","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content_md"],"properties":{"title":{"type":"string"},"content_md":{"type":"string","maxLength":2097152},"visibility":{"$ref":"#/components/schemas/Visibility","default":"private"},"status":{"$ref":"#/components/schemas/Status"},"external_id":{"type":"string"},"change_summary":{"type":"string"},"upsert":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created"},"409":{"description":"External ID conflict"}}}},"/api/v1/files/{id}":{"get":{"summary":"Get metadata and latest Markdown","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Document"},"404":{"description":"Not found"}}},"patch":{"summary":"Update document metadata and privacy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"title":{"type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"},"status":{"$ref":"#/components/schemas/Status"}}}}}},"responses":{"200":{"description":"Updated"}}}},"/api/v1/files/{id}/versions":{"get":{"summary":"List document versions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Versions"}}},"post":{"summary":"Upload a new version","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Created version"}}}},"/api/v1/files/{id}/comments":{"get":{"summary":"List document-level comments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","resolved","all"],"default":"open"}}],"responses":{"200":{"description":"Comments"},"404":{"description":"Not found"}}},"post":{"summary":"Add a document-level comment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Created comment"}}}},"/api/v1/files/{id}/comments/{commentId}/resolve":{"post":{"summary":"Resolve a document-level comment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"commentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Resolved comment"},"404":{"description":"Not found"}}}}}}