{"openapi":"3.1.0","info":{"title":"Endorr Cloud API","version":"1.0.0","description":"Files and folders in Endorr Cloud, by path or by id, with one API key.\n\nAuthenticate with `Authorization: Bearer endorr_sk_…` (create keys in Endorr Studio, Settings, API keys).\n\nPaths start at the key's `/`: the workspace, or the one folder the key is limited to.\n\nEach operation lists the key permission it needs in `x-endorr-permission`. Docs: https://endorr.com/developers."},"externalDocs":{"url":"https://endorr.com/developers"},"servers":[{"url":"https://auth.endorr.com"}],"security":[{"apiKey":[]}],"paths":{"/v1/cloud":{"get":{"operationId":"discover","summary":"What this API is and where its docs, spec and MCP server are. No key needed.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cloud/openapi.json":{"get":{"operationId":"openapi","summary":"This document. No key needed.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cloud/me":{"get":{"operationId":"whoami","summary":"Who the key acts for, its permissions and folder, storage use and limits.","x-endorr-permission":"files.read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/cloud/folders":{"get":{"operationId":"listFolderByPath","summary":"List a folder by path (folders first, then files, by name).","x-endorr-permission":"files.read","parameters":[{"name":"path","in":"query","required":false,"description":"Folder path; default `/`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["folder","items","next_cursor"],"properties":{"folder":{"$ref":"#/components/schemas/Folder"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"}}},"post":{"operationId":"createFolder","summary":"Create a folder and any missing folders above it (mkdir -p). Idempotent.","x-endorr-permission":"files.write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string","example":"/Clients/Acme/2026"}}}}}},"responses":{"200":{"description":"Already there","content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"$ref":"#/components/schemas/Folder"},"created":{"type":"boolean","const":false}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"$ref":"#/components/schemas/Folder"},"created":{"type":"boolean","const":true}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"}}}},"/v1/cloud/folders/{id}":{"get":{"operationId":"listFolder","summary":"List a folder by id.","x-endorr-permission":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"Folder id (`root` = the key's `/`).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["folder","items","next_cursor"],"properties":{"folder":{"$ref":"#/components/schemas/Folder"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"operationId":"updateFolder","summary":"Rename and/or move a folder. `move_to` folders are created when missing.","x-endorr-permission":"files.write","parameters":[{"name":"id","in":"path","required":true,"description":"Folder id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"move_to":{"type":"string","description":"New parent path."},"parent_id":{"type":"string","description":"New parent id, or `root`."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["folder"],"properties":{"folder":{"$ref":"#/components/schemas/Folder"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"}}},"delete":{"operationId":"trashFolder","summary":"Move a folder and its contents to the trash (restorable for 28 days in Studio).","x-endorr-permission":"files.delete","parameters":[{"name":"id","in":"path","required":true,"description":"Folder id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/cloud/folders/{id}/share":{"post":{"operationId":"shareFolder","summary":"Create a view-only share link to a folder.","x-endorr-permission":"shares.create","parameters":[{"name":"id","in":"path","required":true,"description":"Folder id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"default":7},"max_downloads":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"share":{"$ref":"#/components/schemas/Share"}}}}}},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/cloud/files":{"get":{"operationId":"getFileByPath","summary":"A file's details by path.","x-endorr-permission":"files.read","parameters":[{"name":"path","in":"query","required":true,"description":"Path from the key's `/`, e.g. `/Invoices/2026/jan.pdf`. Case-sensitive; no `.` or `..`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"}}},"put":{"operationId":"uploadFile","summary":"Upload in one request (≤100 MB): the body is the file. Missing folders are created.","x-endorr-permission":"files.write","parameters":[{"name":"path","in":"query","required":true,"description":"Path from the key's `/`, e.g. `/Invoices/2026/jan.pdf`. Case-sensitive; no `.` or `..`.","schema":{"type":"string"}},{"name":"on_conflict","in":"query","required":false,"description":"`rename` (default) keeps both (\"name (2).pdf\"); `overwrite` replaces the bytes and keeps the id; `fail` answers 409 already_exists.","schema":{"type":"string","enum":["rename","overwrite","fail"],"default":"rename"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"*/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Overwritten","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"},"replaced":{"type":"boolean","const":true}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"},"replaced":{"type":"boolean","const":false}}}}}},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"413":{"$ref":"#/components/responses/E413"},"422":{"$ref":"#/components/responses/E422"}}},"post":{"operationId":"uploadFilePost","summary":"Same as PUT, for clients that prefer POST.","x-endorr-permission":"files.write","parameters":[{"name":"path","in":"query","required":true,"description":"Path from the key's `/`, e.g. `/Invoices/2026/jan.pdf`. Case-sensitive; no `.` or `..`.","schema":{"type":"string"}},{"name":"on_conflict","in":"query","required":false,"description":"`rename` (default) keeps both (\"name (2).pdf\"); `overwrite` replaces the bytes and keeps the id; `fail` answers 409 already_exists.","schema":{"type":"string","enum":["rename","overwrite","fail"],"default":"rename"}}],"requestBody":{"required":true,"content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"413":{"$ref":"#/components/responses/E413"},"422":{"$ref":"#/components/responses/E422"}}}},"/v1/cloud/files/download":{"get":{"operationId":"downloadFileByPath","summary":"Download a file by path.","x-endorr-permission":"files.read","parameters":[{"name":"path","in":"query","required":true,"description":"Path from the key's `/`, e.g. `/Invoices/2026/jan.pdf`. Case-sensitive; no `.` or `..`.","schema":{"type":"string"}},{"name":"redirect","in":"query","required":false,"description":"`false` answers `{ url, expires_at }` instead of redirecting.","schema":{"type":"string","enum":["false"]}}],"responses":{"200":{"description":"With redirect=false","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}}}}},"302":{"description":"Redirect to a short-lived URL with the bytes. Follow it (curl -L)."},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/v1/cloud/files/{id}":{"get":{"operationId":"getFile","summary":"A file's details by id.","x-endorr-permission":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"operationId":"updateFile","summary":"Rename and/or move a file. `move_to` folders are created when missing.","x-endorr-permission":"files.write","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"move_to":{"type":"string","description":"New folder path."},"folder_id":{"type":"string","description":"New folder id, or `root`."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"}}},"delete":{"operationId":"trashFile","summary":"Move a file to the trash (restorable for 28 days in Studio).","x-endorr-permission":"files.delete","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/cloud/files/{id}/download":{"get":{"operationId":"downloadFile","summary":"Download a file by id.","x-endorr-permission":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}},{"name":"redirect","in":"query","required":false,"description":"`false` answers `{ url, expires_at }` instead of redirecting.","schema":{"type":"string","enum":["false"]}}],"responses":{"200":{"description":"With redirect=false","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}}}}},"302":{"description":"Redirect to a short-lived URL with the bytes. Follow it (curl -L)."},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/v1/cloud/files/{id}/share":{"post":{"operationId":"shareFile","summary":"Create a view-only share link to a file.","x-endorr-permission":"shares.create","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"default":7},"max_downloads":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"share":{"$ref":"#/components/schemas/Share"}}}}}},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/cloud/uploads":{"post":{"operationId":"startLargeUpload","summary":"Start a large upload (≤50 GB): PUT the bytes to upload.url with upload.headers (no API key), then POST complete_url.","x-endorr-permission":"files.write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","size_bytes"],"properties":{"path":{"type":"string"},"size_bytes":{"type":"integer","minimum":0},"content_type":{"type":"string"},"on_conflict":{"type":"string","enum":["rename","fail"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"path":{"type":"string"},"upload":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string"}}},"complete_url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"}}}},"/v1/cloud/uploads/{id}/complete":{"post":{"operationId":"completeLargeUpload","summary":"Confirm a large upload arrived; the file then appears in its folder.","x-endorr-permission":"files.write","parameters":[{"name":"id","in":"path","required":true,"description":"File id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sha256":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/v1/cloud/search":{"get":{"operationId":"search","summary":"Files and folders whose name contains q (case-insensitive), newest first.","x-endorr-permission":"files.read","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"}}}},"/v1/cloud/mcp":{"post":{"operationId":"mcp","summary":"Model Context Protocol server (Streamable HTTP, JSON-RPC 2.0). Connect an AI agent with the same API key; tools mirror this API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request or notification."}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Notification accepted"},"401":{"$ref":"#/components/responses/E401"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"endorr_sk_…","description":"A personal API key from Endorr Studio, Settings, API keys."}},"schemas":{"File":{"type":"object","required":["type","id","name","path"],"properties":{"type":{"const":"file"},"id":{"type":"string","example":"file_01JB8Q2V5M8ZK3F7A1B2C3D4E"},"name":{"type":"string"},"path":{"type":"string","example":"/Invoices/2026/jan.pdf"},"folder_id":{"type":["string","null"]},"size_bytes":{"type":"integer"},"content_type":{"type":"string"},"sha256":{"type":["string","null"]},"status":{"type":"string","enum":["pending","ready"]},"created_via":{"type":"string","description":"`api` for files made with an API key."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Folder":{"type":"object","required":["type","id","name","path"],"properties":{"type":{"const":"folder"},"id":{"type":"string","description":"`root` for the top of a workspace-wide key."},"name":{"type":"string"},"path":{"type":"string","example":"/Invoices"},"parent_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Item":{"oneOf":[{"$ref":"#/components/schemas/File"},{"$ref":"#/components/schemas/Folder"}],"discriminator":{"propertyName":"type"}},"Share":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"resource_type":{"type":"string","enum":["file","folder"]},"resource_id":{"type":"string"},"expires_at":{"type":["string","null"]},"max_downloads":{"type":["integer","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable; branch on this.","examples":["unauthorized","forbidden","not_found","already_exists","validation_failed","storage_quota_exceeded","payload_too_large","rate_limited"]},"message":{"type":"string","description":"For people: says what to do next."},"details":{},"request_id":{"type":"string"},"docs_url":{"type":"string","format":"uri"}}}}}},"responses":{"E401":{"description":"Missing, wrong, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E402":{"description":"Out of storage (storage_quota_exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"The key lacks a permission, or the user cannot edit there","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Nothing at that path or id that this key can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Conflict, e.g. already_exists with on_conflict=fail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E413":{"description":"Over the one-request upload limit (payload_too_large)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"A parameter is missing or wrong (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}