{"openapi":"3.1.0","info":{"title":"txt API","version":"1.0.0","description":"Remote text filesystem for .txt and .md files. Files and folders carry context and reusable tags; related-file discovery uses shared tags and folder membership. Listings are metadata-only and file GETs support ETag / If-None-Match (304).","contact":{"url":"https://www.txt-fil.es"}},"servers":[{"url":"https://www.txt-fil.es","description":"Production"}],"x-api-status":"beta","security":[{"bearerAuth":[]},{"dotsOAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"txt_<key>","description":"Scoped and optionally expiring txt API key. Create one at /sync.","x-scopes":{"files:read":"Allows files read operations","files:write":"Allows files write operations","folders:read":"Allows folders read operations","folders:write":"Allows folders write operations","collaboration:read":"Allows collaboration read operations","collaboration:write":"Allows collaboration write operations","shares:read":"Allows shares read operations","shares:write":"Allows shares write operations","ai:use":"Allows ai use operations"}},"dotsOAuth":{"type":"oauth2","description":"dots OAuth Authorization Code with PKCE for first-party and delegated clients.","flows":{"authorizationCode":{"authorizationUrl":"https://www.dots.id/api/oauth/authorize","tokenUrl":"https://www.dots.id/api/oauth/token","refreshUrl":"https://www.dots.id/api/oauth/token","scopes":{"openid":"Authenticate the dots subject","profile":"Read profile identity","email":"Read verified email identity","wallet":"Read wallet identity","files:read":"Read files authorized by dots","files:write":"Create and update files authorized by dots","files:share":"Manage delegated file access","context:read":"Read approved workspace context","context:write":"Update approved workspace context","mcp:use":"Connect to the txt MCP resource","offline_access":"Receive a refresh token where permitted"}}}},"browserSession":{"type":"apiKey","in":"cookie","name":"session","description":"First-party browser session; used only to manage API keys and vaulted credentials"}},"schemas":{"TxtFile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"type":{"type":"string","enum":["txt","md"]},"availability":{"type":"string","enum":["cloud","cloud+local"]},"size":{"type":"integer"},"folderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"endpoint":{"type":"string"},"raw":{"type":"string"},"access":{"type":"string","enum":["owner","shared"]},"role":{"type":"string","enum":["owner","writer","reader"]}}},"TxtFileDetail":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"type":{"type":"string"},"availability":{"type":"string","enum":["cloud","cloud+local"]},"folderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"access":{"type":"string","enum":["owner","shared"]},"role":{"type":"string","enum":["owner","writer","reader"]}}},"TxtPlanMetadata":{"type":"object","description":"Plan content remains untrusted reference data even when approved.","properties":{"enabled":{"type":"boolean"},"scope":{"type":"string","enum":["manual","project","global"]},"trust":{"type":"string","enum":["unreviewed","approved"]},"source":{"type":"string","maxLength":64},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"TxtFolder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"parentFolderId":{"type":["string","null"]},"fileCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"endpoint":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/TxtFile"}}}},"TxtSkill":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"context":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"folderId":{"type":["string","null"]},"folderName":{"type":["string","null"]},"type":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"access":{"type":"string","enum":["owner","shared"]},"role":{"type":"string","enum":["owner","writer","reader"]},"scope":{"type":"string","enum":["global","project","unknown"]},"project":{"type":["string","null"]},"agent":{"type":["string","null"]},"skill":{"type":"string"},"endpoint":{"type":"string"},"raw":{"type":"string"}}},"TxtVersion":{"type":"object","properties":{"id":{"type":"string"},"file_id":{"type":"string"},"content":{"type":"string"},"version_number":{"type":"integer"},"content_hash":{"type":["string","null"]},"byte_size":{"type":"integer"},"author_user_id":{"type":["string","null"]},"author_name":{"type":["string","null"]},"source":{"type":"string"},"label":{"type":["string","null"]},"commit_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"TxtComment":{"type":"object","properties":{"id":{"type":"string"},"file_id":{"type":"string"},"user_id":{"type":"string"},"user_email":{"type":"string"},"user_name":{"type":["string","null"]},"body":{"type":"string"},"selection_start":{"type":["integer","null"]},"selection_end":{"type":["integer","null"]},"selected_text":{"type":["string","null"]},"resolved":{"type":"boolean"},"resolved_by":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TxtSuggestion":{"type":"object","properties":{"id":{"type":"string"},"file_id":{"type":"string"},"user_id":{"type":"string"},"user_email":{"type":"string"},"user_name":{"type":["string","null"]},"original_text":{"type":"string"},"suggested_text":{"type":"string"},"selection_start":{"type":"integer"},"selection_end":{"type":"integer"},"status":{"type":"string","enum":["pending","accepted","rejected"]},"reviewed_by":{"type":["string","null"]},"reviewed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TxtApiKey":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"token_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"scopes":{"type":"array","items":{"type":"string","enum":["files:read","files:write","folders:read","folders:write","collaboration:read","collaboration:write","shares:read","shares:write","ai:use"]}},"requests_today":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","resolution","requestId"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"resolution":{"type":"string"},"requestId":{"type":"string"}}}}},"JsonObject":{"type":"object","description":"Typed JSON object; operation-specific fields are additive unless otherwise documented.","additionalProperties":true}}},"paths":{"/api/me":{"get":{"operationId":"listFiles","summary":"List all files and folders","tags":["Files"],"responses":{"200":{"description":"File tree","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}},"identity":{"nullable":true,"type":"object","properties":{"provider":{"type":"string","enum":["dots"]},"issuer":{"type":"string","format":"uri"},"subject":{"type":"string"},"username":{"type":["string","null"]},"status":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"verificationError":{"type":["string","null"]},"wallet":{"nullable":true,"type":"object","properties":{"address":{"type":"string"},"chainType":{"type":["string","null"]},"network":{"type":["string","null"]},"walletType":{"type":["string","null"]}}}}},"folders":{"type":"array","items":{"$ref":"#/components/schemas/TxtFolder"}},"rootFiles":{"type":"array","items":{"$ref":"#/components/schemas/TxtFile"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List all files and folders"}},"/api/me/files":{"get":{"operationId":"listFlatFiles","summary":"List all file metadata without bodies","tags":["Files"],"responses":{"200":{"description":"Flat file index","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List all file metadata without bodies"},"post":{"operationId":"createFile","summary":"Create a .txt or .md file","tags":["Files"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"content":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"fileType":{"type":"string","enum":["txt","md"]},"availability":{"type":"string","enum":["cloud","cloud+local"],"default":"cloud+local"},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"File created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a .txt or .md file"}},"/api/me/files/{id}":{"get":{"operationId":"getFile","summary":"Get file metadata and content","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxtFileDetail"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get file metadata and content"},"put":{"operationId":"updateFile","summary":"Update file content or name","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"fileType":{"type":"string","enum":["txt","md"]},"availability":{"type":"string","enum":["cloud","cloud+local"]},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated file","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/TxtFileDetail"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update file content or name"}},"/api/me/files/{id}/raw":{"get":{"operationId":"getFileRaw","summary":"Get raw file content (plain text, no JSON)","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw text content","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get raw file content (plain text, no JSON)"}},"/api/me/files/{id}/plan":{"get":{"operationId":"getFilePlanMetadata","summary":"Get plan-brain scope and trust metadata","tags":["Plans"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plan metadata","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/TxtPlanMetadata"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get plan-brain scope and trust metadata"},"put":{"operationId":"updateFilePlanMetadata","summary":"Owner-only plan classification and approval","tags":["Plans"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled","scope","trust"],"properties":{"enabled":{"type":"boolean"},"scope":{"type":"string","enum":["manual","project","global"]},"trust":{"type":"string","enum":["unreviewed","approved"]},"source":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"Plan metadata updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Only the owner may update plan metadata","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Owner-only plan classification and approval"}},"/api/me/files/{id}/connections":{"get":{"operationId":"getFileConnections","summary":"Discover explicit and inferred related files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked related files with connection reasons","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Discover explicit and inferred related files"},"post":{"operationId":"connectFiles","summary":"Create or update an explicit connection between two files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetFileId"],"properties":{"targetFileId":{"type":"string"},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Files connected","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create or update an explicit connection between two files"},"delete":{"operationId":"disconnectFiles","summary":"Remove an explicit connection between two files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"targetFileId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connection removed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Remove an explicit connection between two files"}},"/api/me/ideation":{"get":{"operationId":"listIdeationNotes","summary":"List ideation notes and whether the brain can explore","tags":["Ideation"],"responses":{"200":{"description":"Ideation access plus recent notes","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List ideation notes and whether the brain can explore"},"post":{"operationId":"createIdeationNote","summary":"Create a note that explores itself from the context brain","tags":["Ideation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Grown ideation note with folder, tags, and connections","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Subscription or BYOK required","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a note that explores itself from the context brain"}},"/api/me/files/{id}/ideation":{"get":{"operationId":"getFileIdeation","summary":"Get ideation status for a note","tags":["Ideation"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ideation metadata","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get ideation status for a note"}},"/api/me/files/{id}/ideate":{"post":{"operationId":"growIdeationNote","summary":"Grow an existing note from the context brain","tags":["Ideation"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Updated ideation note","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Subscription or BYOK required","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner only","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Grow an existing note from the context brain"}},"/api/me/context":{"get":{"operationId":"getWorkspaceContext","summary":"Get workspace metadata and organization coverage","tags":["Context"],"responses":{"200":{"description":"Workspace context","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get workspace metadata and organization coverage"},"post":{"operationId":"analyzeWorkspaceContext","summary":"Propose context, tags, folders, and file connections","tags":["Context"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Reviewable workspace proposals","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AI is not activated with a user key","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Propose context, tags, folders, and file connections"}},"/api/identity/jazz":{"get":{"operationId":"discoverDotsJazz","summary":"Discover Jazz configuration for the signed-in dots identity","description":"Uses the server-held dots access token. Jazz is connectable when configured is true, syncMode is not off, and syncServer is present. Expired dots tokens return 401 DOTS_REAUTH_REQUIRED. Turso remains the fallback.","tags":["Identity"],"responses":{"200":{"description":"Normalized dots/Jazz capability","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized or dots reauth required","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No dots identity linked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"dots capability discovery failed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/folders":{"get":{"operationId":"listFolders","summary":"List folder metadata","tags":["Folders"],"responses":{"200":{"description":"Folders","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List folder metadata"},"post":{"operationId":"createFolder","summary":"Create a folder with context and tags","tags":["Folders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"parentFolderId":{"type":["string","null"],"description":"Parent folder; null creates at root"}}}}}},"responses":{"200":{"description":"Folder created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a folder with context and tags"}},"/api/me/folders/{id}":{"get":{"operationId":"getFolder","summary":"Get folder with nested files (includes content)","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxtFolder"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get folder with nested files (includes content)"},"put":{"operationId":"updateFolder","summary":"Update folder name, context, tags, or parent","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"parentFolderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Folder updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update folder name, context, tags, or parent"},"delete":{"operationId":"deleteFolder","summary":"Delete folder and promote direct files and subfolders one level","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Delete folder and promote direct files and subfolders one level"}},"/api/me/skills":{"get":{"operationId":"listSkills","summary":"List published agent skills, including collaborator shares","description":"Returns notes in a folder named skills or named *SKILL.md. txt-cli publishes global trees as claude/ship/SKILL.md and project trees as project/<repo>/claude/review/SKILL.md.","tags":["Skills"],"responses":{"200":{"description":"Published skills","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/TxtSkill"}},"reveal":{"type":"string","format":"uri"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/skills/catalog":{"get":{"operationId":"searchSkillCatalog","summary":"Search the federated skills catalog","description":"Searches txt/groupSkills plus a frequently refreshed, content-enriched mirror of skills.sh. Multi-word queries use upstream semantic ranking and merge it with cached descriptions, topics, publishers, rankings, and install statistics. Omit q for the selected leaderboard view.","tags":["Skills"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160}},{"name":"owner","in":"query","description":"Company, GitHub owner, or publisher","schema":{"type":"string","maxLength":100}},{"name":"view","in":"query","schema":{"type":"string","enum":["trending","hot","all-time","official","txt"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Catalog matches","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalog unavailable before its first successful refresh","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/skills/install":{"post":{"operationId":"installSkill","summary":"Add selected skills.sh files to a txt cloud folder","description":"Fetches the current security audit and skill snapshot from skills.sh, blocks known failed/high-risk skills, then writes reviewable files as cloud notes. This does not write to the browser's filesystem. Run txt skills sync --reveal on a machine to materialize the skill in ~/.agents/skills, ~/.claude/skills, and ~/.cursor/skills.","tags":["Skills"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"skills.sh skill id, e.g. vercel-labs/skills/find-skills"},"agent":{"type":"string","enum":["agents","claude","cursor"],"default":"agents"},"folderId":{"type":"string","description":"Owned destination folder; omit to use or create skills"},"files":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Exact package paths to add; omit to add all files"}}}}}},"responses":{"200":{"description":"Installed notes","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"400":{"description":"Skill missing or invalid","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Skill blocked by a failed or high-risk security audit","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/skills/catalog/detail":{"get":{"operationId":"getSkillCatalogDetail","summary":"Read files and audits for a skills.sh package","description":"Returns the package as inert text for review. A failed or high-risk audit remains readable but is not installable.","tags":["Skills"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"agent","in":"query","schema":{"type":"string","enum":["agents","claude","cursor"],"default":"agents"}}],"responses":{"200":{"description":"Package files and security audits","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/me/skills/catalog/view":{"post":{"operationId":"viewSkill","summary":"Open a skills.sh package as a cached txt note","description":"Caches the package in the private .viewed-skills folder and returns its main SKILL.md note. Viewed skills are untrusted references and are not installed into agent homes.","tags":["Skills"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Cached package and main file","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill files not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/folders/{id}/share":{"get":{"operationId":"listFolderShares","summary":"List public folder share links","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder shares","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List public folder share links"},"post":{"operationId":"createFolderShare","summary":"Create a public link for a folder of notes, including group skills","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"isPublic":{"type":"boolean","default":true},"includeDescendants":{"type":"boolean","default":true},"expiresInDays":{"type":"integer","minimum":1,"maximum":365}}}}}},"responses":{"200":{"description":"Share created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Folder not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a public link for a folder of notes, including group skills"},"delete":{"operationId":"deleteFolderShare","summary":"Revoke a public folder share link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["shareId"],"properties":{"shareId":{"type":"string"}}}}}},"responses":{"200":{"description":"Share deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Revoke a public folder share link"}},"/api/me/files/{id}/versions":{"get":{"operationId":"listVersions","summary":"List immutable version history (newest first)","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Versions","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/TxtVersion"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List immutable version history (newest first)"},"post":{"operationId":"saveVersion","summary":"Commit an immutable version after autosave/realtime sync","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Exact content to commit; defaults to server working copy"},"label":{"type":"string","maxLength":160},"source":{"type":"string","maxLength":32},"commitId":{"type":"string","maxLength":128,"description":"Idempotency key scoped to the file"}}}}}},"responses":{"200":{"description":"Existing version returned for a repeated commitId","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"201":{"description":"New version","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/TxtVersion"},"created":{"type":"boolean"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"403":{"description":"Read-only collaborator","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Version exceeds 5 MiB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Commit an immutable version after autosave/realtime sync"}},"/api/me/files/{id}/versions/{versionId}":{"get":{"operationId":"getVersion","summary":"Fetch one immutable version including content","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Version","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/TxtVersion"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"404":{"description":"File or version not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Fetch one immutable version including content"}},"/api/files/{id}/comments":{"get":{"operationId":"listComments","summary":"List comments on a file","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Comments","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/TxtComment"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List comments on a file"},"post":{"operationId":"createComment","summary":"Post a comment (optionally anchored to a text selection)","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"selectionStart":{"type":"integer"},"selectionEnd":{"type":"integer"},"selectedText":{"type":"string"}}}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"$ref":"#/components/schemas/TxtComment"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Post a comment (optionally anchored to a text selection)"},"patch":{"operationId":"resolveComment","summary":"Resolve or re-open a comment","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["commentId","resolved"],"properties":{"commentId":{"type":"string"},"resolved":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Resolve or re-open a comment"},"delete":{"operationId":"deleteComment","summary":"Delete a comment","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Delete a comment"}},"/api/files/{id}/suggestions":{"get":{"operationId":"listSuggestions","summary":"List track-change suggestions on a file","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/TxtSuggestion"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List track-change suggestions on a file"},"post":{"operationId":"createSuggestion","summary":"Submit a track-change suggestion","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["suggestedText","selectionStart","selectionEnd"],"properties":{"originalText":{"type":"string"},"suggestedText":{"type":"string"},"selectionStart":{"type":"integer"},"selectionEnd":{"type":"integer"}}}}}},"responses":{"201":{"description":"Suggestion created","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"$ref":"#/components/schemas/TxtSuggestion"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Submit a track-change suggestion"},"patch":{"operationId":"reviewSuggestion","summary":"Accept or reject a suggestion","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["suggestionId","status"],"properties":{"suggestionId":{"type":"string"},"status":{"type":"string","enum":["accepted","rejected"]}}}}}},"responses":{"200":{"description":"Updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Accept or reject a suggestion"}},"/api/me/keys":{"get":{"operationId":"listApiKeys","summary":"List API keys for the current user","tags":["API Keys"],"security":[{"browserSession":[]}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/TxtApiKey"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List API keys for the current user"},"post":{"operationId":"createApiKey","summary":"Create a new API key","tags":["API Keys"],"security":[{"browserSession":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":80},"scopes":{"type":"array","items":{"type":"string"}},"expiresInDays":{"type":["integer","null"],"enum":[1,7,30,90,365,null]}}}}}},"responses":{"200":{"description":"Key created — token shown once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"token":{"type":"string","description":"Full token — only returned once, store it securely"},"token_prefix":{"type":"string"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Create a new API key"},"patch":{"operationId":"rotateApiKey","summary":"Rotate an API key; the replacement token is shown once","tags":["API Keys"],"security":[{"browserSession":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Replacement key","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Rotate an API key; the replacement token is shown once"},"put":{"operationId":"updateApiKey","summary":"Update a key label, scopes, and expiry","tags":["API Keys"],"security":[{"browserSession":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","scopes","expiresInDays"],"properties":{"id":{"type":"string"},"label":{"type":"string","maxLength":80},"scopes":{"type":"array","items":{"type":"string"}},"expiresInDays":{"type":["integer","null"],"enum":[1,7,30,90,365,null]}}}}}},"responses":{"200":{"description":"Key updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Update a key label, scopes, and expiry"},"delete":{"operationId":"deleteApiKey","summary":"Revoke an API key","tags":["API Keys"],"security":[{"browserSession":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Revoke an API key"}},"/api/me/files/{id}/sync":{"get":{"operationId":"getFileSyncPolicy","summary":"Get the effective dots sync policy for a file","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync policy","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get the effective dots sync policy for a file"},"put":{"operationId":"setFileSyncPolicy","summary":"Set dots sync inheritance for a file","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["inherit","on","off"]}}}}}},"responses":{"200":{"description":"Sync policy updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Set dots sync inheritance for a file"}},"/api/me/folders/{id}/sync":{"get":{"operationId":"getFolderSyncPolicy","summary":"Get the effective dots sync policy for a folder","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync policy","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get the effective dots sync policy for a folder"},"put":{"operationId":"setFolderSyncPolicy","summary":"Set dots sync inheritance for a folder","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["inherit","on","off"]}}}}}},"responses":{"200":{"description":"Sync policy updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Set dots sync inheritance for a folder"}},"/api/shares":{"post":{"operationId":"createShareLink","summary":"Create or rotate a live capability link to a cloud file","description":"When fileId is supplied, the link always reads the current canonical file. Snapshot fields remain accepted only for backward compatibility.","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["fileId","mode"],"properties":{"fileId":{"type":"string"},"mode":{"type":"string","enum":["public","readonly","password","password-readonly"]},"password":{"type":"string","writeOnly":true}}}}}},"responses":{"200":{"description":"Copy-ready publicUrl and capability token","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"File not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"readShareLink","summary":"Read the current file through a capability link","description":"token or slug reads publicly; fileId inspects the owner's active link and requires authentication.","security":[],"tags":["Shares"],"parameters":[{"name":"token","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"fileId","in":"query","schema":{"type":"string"}},{"name":"X-Txt-Share-Password","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Live file content","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Password required or invalid","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or revoked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateThroughShareLink","summary":"Update the canonical file through an editable capability link","security":[],"tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token","content"],"properties":{"token":{"type":"string"},"content":{"type":"string"},"password":{"type":"string","writeOnly":true}}}}}},"responses":{"200":{"description":"Canonical file updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"403":{"description":"Read-only share","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Concurrent snapshot update","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update the canonical file through an editable capability link"},"delete":{"operationId":"revokeShareLink","summary":"Revoke an owned capability link","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Revoke an owned capability link"}},"/api/me/ai":{"get":{"operationId":"getAiAccount","summary":"Get user-activated provider preference, credential metadata, and usage","tags":["AI"],"responses":{"200":{"description":"AI account status","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get user-activated provider preference, credential metadata, and usage"},"put":{"operationId":"setAiProvider","summary":"Select a configured AI provider","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["provider","model"],"properties":{"provider":{"type":"string","enum":["gateway","openai","anthropic"]},"model":{"type":"string","maxLength":128}}}}}},"responses":{"200":{"description":"Provider selected","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"409":{"description":"Identity or credential is not configured","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Select a configured AI provider"}},"/api/me/ai/credentials":{"get":{"operationId":"listAiCredentials","summary":"List write-only vault metadata","security":[{"browserSession":[]}],"tags":["AI"],"responses":{"200":{"description":"Credential metadata; never secrets","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"List write-only vault metadata"},"put":{"operationId":"saveAiCredential","summary":"Verify and encrypt a browser-session BYOK credential","security":[{"browserSession":[]}],"tags":["AI"],"responses":{"200":{"description":"Credential saved","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"503":{"description":"Vault is not configured","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Verify and encrypt a browser-session BYOK credential"},"delete":{"operationId":"revokeAiCredential","summary":"Delete a BYOK credential","security":[{"browserSession":[]}],"tags":["AI"],"responses":{"204":{"description":"Credential deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Delete a BYOK credential"}},"/api/ai/assist":{"post":{"operationId":"assistText","summary":"Generate a reviewable rewrite using the account provider","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":20000},"action":{"type":"string","enum":["improve","fix","shorter","longer","formal","casual","custom"]},"customPrompt":{"type":"string","maxLength":4000}}}}}},"responses":{"200":{"description":"Suggestion plus provider/model/token usage","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"409":{"description":"AI is not activated with a user key","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Generate a reviewable rewrite using the account provider"}},"/api/me/transcriptions":{"post":{"operationId":"transcribeHandwrittenNote","summary":"Transcribe an uploaded or remote handwritten-note image into a synced txt file","description":"Requires both ai:use and files:write. Uses the account's activated BYOK vision provider. Remote images are fetched through a bounded, HTTPS-only, private-network-denying loader. The image is not stored.","tags":["AI","Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageBase64":{"type":"string","description":"Base64 JPEG, PNG, GIF, or WebP; maximum decoded size 10 MiB"},"imageUrl":{"type":"string","format":"uri","description":"HTTPS image URL; mutually exclusive with imageBase64"},"mediaType":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp"]},"mode":{"type":"string","enum":["structured","verbatim"],"default":"structured"},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"],"default":"md"},"folderId":{"type":["string","null"]}},"oneOf":[{"required":["imageBase64"]},{"required":["imageUrl"]}]}},"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"mode":{"type":"string","enum":["structured","verbatim"]},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"]},"folderId":{"type":["string","null"]}}}}}},"responses":{"201":{"description":"Created txt file plus provider, model, image digest, mode, and usage","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"400":{"description":"Invalid image or options","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A BYOK vision provider is not active","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image is too large","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported or mismatched image type","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files":{"get":{"operationId":"v1ListFlatFiles","summary":"List all file metadata without bodies","tags":["Files"],"responses":{"200":{"description":"Flat file index","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","description":"Case-insensitive name/context search","schema":{"type":"string","maxLength":100}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["txt","md"]}},{"name":"folderId","in":"query","description":"Folder ID or root","schema":{"type":"string"}},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"}}],"description":"List all file metadata without bodies"},"post":{"operationId":"v1CreateFile","summary":"Create a .txt or .md file","tags":["Files"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"content":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"fileType":{"type":"string","enum":["txt","md"]},"availability":{"type":"string","enum":["cloud","cloud+local"],"default":"cloud+local"},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"File created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a .txt or .md file"}},"/api/v1/files/{id}":{"get":{"operationId":"v1GetFile","summary":"Get file metadata and content","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxtFileDetail"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get file metadata and content"},"put":{"operationId":"v1UpdateFile","summary":"Update file content or name","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"fileType":{"type":"string","enum":["txt","md"]},"availability":{"type":"string","enum":["cloud","cloud+local"]},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated file","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/TxtFileDetail"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update file content or name"}},"/api/v1/files/{id}/raw":{"get":{"operationId":"v1GetFileRaw","summary":"Get raw file content (plain text, no JSON)","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw text content","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get raw file content (plain text, no JSON)"}},"/api/v1/files/{id}/versions":{"get":{"operationId":"v1ListVersions","summary":"List immutable version history (newest first)","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Versions","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/TxtVersion"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List immutable version history (newest first)"},"post":{"operationId":"v1SaveVersion","summary":"Commit an immutable version after autosave/realtime sync","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Exact content to commit; defaults to server working copy"},"label":{"type":"string","maxLength":160},"source":{"type":"string","maxLength":32},"commitId":{"type":"string","maxLength":128,"description":"Idempotency key scoped to the file"}}}}}},"responses":{"200":{"description":"Existing version returned for a repeated commitId","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"201":{"description":"New version","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/TxtVersion"},"created":{"type":"boolean"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"403":{"description":"Read-only collaborator","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Version exceeds 5 MiB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Commit an immutable version after autosave/realtime sync"}},"/api/v1/files/{id}/versions/{versionId}":{"get":{"operationId":"v1GetVersion","summary":"Fetch one immutable version including content","tags":["Versions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Version","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/TxtVersion"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"404":{"description":"File or version not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Fetch one immutable version including content"}},"/api/v1/files/{id}/comments":{"get":{"operationId":"v1ListComments","summary":"List comments on a file","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Comments","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/TxtComment"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List comments on a file"},"post":{"operationId":"v1CreateComment","summary":"Post a comment (optionally anchored to a text selection)","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"selectionStart":{"type":"integer"},"selectionEnd":{"type":"integer"},"selectedText":{"type":"string"}}}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"$ref":"#/components/schemas/TxtComment"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Post a comment (optionally anchored to a text selection)"},"patch":{"operationId":"v1ResolveComment","summary":"Resolve or re-open a comment","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["commentId","resolved"],"properties":{"commentId":{"type":"string"},"resolved":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Resolve or re-open a comment"},"delete":{"operationId":"v1DeleteComment","summary":"Delete a comment","tags":["Comments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"commentId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Delete a comment"}},"/api/v1/files/{id}/suggestions":{"get":{"operationId":"v1ListSuggestions","summary":"List track-change suggestions on a file","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/TxtSuggestion"}}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"List track-change suggestions on a file"},"post":{"operationId":"v1CreateSuggestion","summary":"Submit a track-change suggestion","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["suggestedText","selectionStart","selectionEnd"],"properties":{"originalText":{"type":"string"},"suggestedText":{"type":"string"},"selectionStart":{"type":"integer"},"selectionEnd":{"type":"integer"}}}}}},"responses":{"201":{"description":"Suggestion created","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"$ref":"#/components/schemas/TxtSuggestion"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}}},"description":"Submit a track-change suggestion"},"patch":{"operationId":"v1ReviewSuggestion","summary":"Accept or reject a suggestion","tags":["Suggestions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["suggestionId","status"],"properties":{"suggestionId":{"type":"string"},"status":{"type":"string","enum":["accepted","rejected"]}}}}}},"responses":{"200":{"description":"Updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Accept or reject a suggestion"}},"/api/v1/files/{id}/connections":{"get":{"operationId":"v1GetFileConnections","summary":"Discover explicit and inferred related files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked related files with connection reasons","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Discover explicit and inferred related files"},"post":{"operationId":"v1ConnectFiles","summary":"Create or update an explicit connection between two files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetFileId"],"properties":{"targetFileId":{"type":"string"},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Files connected","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create or update an explicit connection between two files"},"delete":{"operationId":"v1DisconnectFiles","summary":"Remove an explicit connection between two files","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"targetFileId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connection removed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Remove an explicit connection between two files"}},"/api/v1/files/{id}/plan":{"get":{"operationId":"v1GetFilePlanMetadata","summary":"Get plan-brain scope and trust metadata","tags":["Plans"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plan metadata","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/TxtPlanMetadata"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get plan-brain scope and trust metadata"},"put":{"operationId":"v1UpdateFilePlanMetadata","summary":"Owner-only plan classification and approval","tags":["Plans"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled","scope","trust"],"properties":{"enabled":{"type":"boolean"},"scope":{"type":"string","enum":["manual","project","global"]},"trust":{"type":"string","enum":["unreviewed","approved"]},"source":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"Plan metadata updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Only the owner may update plan metadata","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Owner-only plan classification and approval"}},"/api/v1/files/{id}/ideation":{"get":{"operationId":"v1GetFileIdeation","summary":"Get ideation status for a note","tags":["Ideation"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ideation metadata","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get ideation status for a note"}},"/api/v1/files/{id}/ideate":{"post":{"operationId":"v1GrowIdeationNote","summary":"Grow an existing note from the context brain","tags":["Ideation"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Updated ideation note","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Subscription or BYOK required","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner only","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Grow an existing note from the context brain"}},"/api/v1/files/{id}/sync":{"get":{"operationId":"v1GetFileSyncPolicy","summary":"Get the effective dots sync policy for a file","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync policy","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get the effective dots sync policy for a file"},"put":{"operationId":"v1SetFileSyncPolicy","summary":"Set dots sync inheritance for a file","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["inherit","on","off"]}}}}}},"responses":{"200":{"description":"Sync policy updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Set dots sync inheritance for a file"}},"/api/v1/ideation":{"get":{"operationId":"v1ListIdeationNotes","summary":"List ideation notes and whether the brain can explore","tags":["Ideation"],"responses":{"200":{"description":"Ideation access plus recent notes","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List ideation notes and whether the brain can explore"},"post":{"operationId":"v1CreateIdeationNote","summary":"Create a note that explores itself from the context brain","tags":["Ideation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Grown ideation note with folder, tags, and connections","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Subscription or BYOK required","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a note that explores itself from the context brain"}},"/api/v1/folders":{"get":{"operationId":"v1ListFolders","summary":"List folder metadata","tags":["Folders"],"responses":{"200":{"description":"Folders","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List folder metadata"},"post":{"operationId":"v1CreateFolder","summary":"Create a folder with context and tags","tags":["Folders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"parentFolderId":{"type":["string","null"],"description":"Parent folder; null creates at root"}}}}}},"responses":{"200":{"description":"Folder created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a folder with context and tags"}},"/api/v1/folders/{id}":{"get":{"operationId":"v1GetFolder","summary":"Get folder with nested files (includes content)","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxtFolder"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get folder with nested files (includes content)"},"put":{"operationId":"v1UpdateFolder","summary":"Update folder name, context, tags, or parent","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"parentFolderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Folder updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update folder name, context, tags, or parent"},"delete":{"operationId":"v1DeleteFolder","summary":"Delete folder and promote direct files and subfolders one level","tags":["Folders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Delete folder and promote direct files and subfolders one level"}},"/api/v1/folders/{id}/sync":{"get":{"operationId":"v1GetFolderSyncPolicy","summary":"Get the effective dots sync policy for a folder","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync policy","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get the effective dots sync policy for a folder"},"put":{"operationId":"v1SetFolderSyncPolicy","summary":"Set dots sync inheritance for a folder","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["inherit","on","off"]}}}}}},"responses":{"200":{"description":"Sync policy updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Set dots sync inheritance for a folder"}},"/api/v1/folders/{id}/share":{"get":{"operationId":"v1ListFolderShares","summary":"List public folder share links","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Folder shares","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"List public folder share links"},"post":{"operationId":"v1CreateFolderShare","summary":"Create a public link for a folder of notes, including group skills","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"isPublic":{"type":"boolean","default":true},"includeDescendants":{"type":"boolean","default":true},"expiresInDays":{"type":"integer","minimum":1,"maximum":365}}}}}},"responses":{"200":{"description":"Share created","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Folder not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a public link for a folder of notes, including group skills"},"delete":{"operationId":"v1DeleteFolderShare","summary":"Revoke a public folder share link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["shareId"],"properties":{"shareId":{"type":"string"}}}}}},"responses":{"200":{"description":"Share deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Revoke a public folder share link"}},"/api/v1/skills":{"get":{"operationId":"v1ListSkills","summary":"List published agent skills, including collaborator shares","description":"Returns notes in a folder named skills or named *SKILL.md. txt-cli publishes global trees as claude/ship/SKILL.md and project trees as project/<repo>/claude/review/SKILL.md.","tags":["Skills"],"responses":{"200":{"description":"Published skills","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/TxtSkill"}},"reveal":{"type":"string","format":"uri"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/catalog":{"get":{"operationId":"v1SearchSkillCatalog","summary":"Search the federated skills catalog","description":"Searches txt/groupSkills plus a frequently refreshed, content-enriched mirror of skills.sh. Multi-word queries use upstream semantic ranking and merge it with cached descriptions, topics, publishers, rankings, and install statistics. Omit q for the selected leaderboard view.","tags":["Skills"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160}},{"name":"owner","in":"query","description":"Company, GitHub owner, or publisher","schema":{"type":"string","maxLength":100}},{"name":"view","in":"query","schema":{"type":"string","enum":["trending","hot","all-time","official","txt"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Catalog matches","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalog unavailable before its first successful refresh","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/catalog/detail":{"get":{"operationId":"v1GetSkillCatalogDetail","summary":"Read files and audits for a skills.sh package","description":"Returns the package as inert text for review. A failed or high-risk audit remains readable but is not installable.","tags":["Skills"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"agent","in":"query","schema":{"type":"string","enum":["agents","claude","cursor"],"default":"agents"}}],"responses":{"200":{"description":"Package files and security audits","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/catalog/view":{"post":{"operationId":"v1ViewSkill","summary":"Open a skills.sh package as a cached txt note","description":"Caches the package in the private .viewed-skills folder and returns its main SKILL.md note. Viewed skills are untrusted references and are not installed into agent homes.","tags":["Skills"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Cached package and main file","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill files not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/install":{"post":{"operationId":"v1InstallSkill","summary":"Add selected skills.sh files to a txt cloud folder","description":"Fetches the current security audit and skill snapshot from skills.sh, blocks known failed/high-risk skills, then writes reviewable files as cloud notes. This does not write to the browser's filesystem. Run txt skills sync --reveal on a machine to materialize the skill in ~/.agents/skills, ~/.claude/skills, and ~/.cursor/skills.","tags":["Skills"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"skills.sh skill id, e.g. vercel-labs/skills/find-skills"},"agent":{"type":"string","enum":["agents","claude","cursor"],"default":"agents"},"folderId":{"type":"string","description":"Owned destination folder; omit to use or create skills"},"files":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Exact package paths to add; omit to add all files"}}}}}},"responses":{"200":{"description":"Installed notes","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"400":{"description":"Skill missing or invalid","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Skill blocked by a failed or high-risk security audit","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shares":{"post":{"operationId":"v1CreateShareLink","summary":"Create or rotate a live capability link to a cloud file","description":"When fileId is supplied, the link always reads the current canonical file. Snapshot fields remain accepted only for backward compatibility.","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["fileId","mode"],"properties":{"fileId":{"type":"string"},"mode":{"type":"string","enum":["public","readonly","password","password-readonly"]},"password":{"type":"string","writeOnly":true}}}}}},"responses":{"200":{"description":"Copy-ready publicUrl and capability token","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"File not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"v1ReadShareLink","summary":"Read the current file through a capability link","description":"token or slug reads publicly; fileId inspects the owner's active link and requires authentication.","tags":["Shares"],"parameters":[{"name":"token","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"fileId","in":"query","schema":{"type":"string"}},{"name":"X-Txt-Share-Password","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Live file content","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Password required or invalid","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or revoked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"v1UpdateThroughShareLink","summary":"Update the canonical file through an editable capability link","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token","content"],"properties":{"token":{"type":"string"},"content":{"type":"string"},"password":{"type":"string","writeOnly":true}}}}}},"responses":{"200":{"description":"Canonical file updated","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"403":{"description":"Read-only share","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Concurrent snapshot update","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Update the canonical file through an editable capability link"},"delete":{"operationId":"v1RevokeShareLink","summary":"Revoke an owned capability link","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Revoke an owned capability link"}},"/api/v1/context":{"get":{"operationId":"v1GetWorkspaceContext","summary":"Get workspace metadata and organization coverage","tags":["Context"],"responses":{"200":{"description":"Workspace context","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Get workspace metadata and organization coverage"},"post":{"operationId":"v1AnalyzeWorkspaceContext","summary":"Propose context, tags, folders, and file connections","tags":["Context"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Reviewable workspace proposals","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AI is not activated with a user key","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Propose context, tags, folders, and file connections"}},"/api/v1/ai/assist":{"post":{"operationId":"v1AssistText","summary":"Generate a reviewable rewrite using the account provider","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":20000},"action":{"type":"string","enum":["improve","fix","shorter","longer","formal","casual","custom"]},"customPrompt":{"type":"string","maxLength":4000}}}}}},"responses":{"200":{"description":"Suggestion plus provider/model/token usage","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"409":{"description":"AI is not activated with a user key","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Generate a reviewable rewrite using the account provider"}},"/api/v1/transcriptions":{"post":{"operationId":"v1TranscribeHandwrittenNote","summary":"Transcribe an uploaded or remote handwritten-note image into a synced txt file","description":"Requires both ai:use and files:write. Uses the account's activated BYOK vision provider. Remote images are fetched through a bounded, HTTPS-only, private-network-denying loader. The image is not stored.","tags":["AI","Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageBase64":{"type":"string","description":"Base64 JPEG, PNG, GIF, or WebP; maximum decoded size 10 MiB"},"imageUrl":{"type":"string","format":"uri","description":"HTTPS image URL; mutually exclusive with imageBase64"},"mediaType":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp"]},"mode":{"type":"string","enum":["structured","verbatim"],"default":"structured"},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"],"default":"md"},"folderId":{"type":["string","null"]}},"oneOf":[{"required":["imageBase64"]},{"required":["imageUrl"]}]}},"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"mode":{"type":"string","enum":["structured","verbatim"]},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"]},"folderId":{"type":["string","null"]}}}}}},"responses":{"201":{"description":"Created txt file plus provider, model, image digest, mode, and usage","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"400":{"description":"Invalid image or options","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A BYOK vision provider is not active","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image is too large","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported or mismatched image type","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1":{"get":{"operationId":"getApiV1Discovery","summary":"Discover v1 resources, limits, and scopes","tags":["API"],"responses":{"200":{"description":"API discovery document","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Discover v1 resources, limits, and scopes"}},"/api/v1/session":{"get":{"operationId":"getV1Session","summary":"Resolve the current API or dots OAuth identity","tags":["Auth"],"responses":{"200":{"description":"Authenticated user and auth method","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Resolve the current API or dots OAuth identity"}},"/api/v1/changes":{"get":{"operationId":"listV1Changes","summary":"Pull ordered changes and delete tombstones after a sync cursor","description":"Bootstrap from file/folder listings, store highWaterMark, then consume this feed. A 410 response means the cursor expired and the client must re-bootstrap.","tags":["Sync"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":200}}],"responses":{"200":{"description":"Ordered change page","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"410":{"description":"Cursor expired; perform a full bootstrap","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/batch":{"post":{"operationId":"runV1Batch","summary":"Run up to 25 ordered file or folder operations","description":"Each operation is independently scope-checked and returns its own status, body, ETag, and trace headers. Put Idempotency-Key on the outer request to retry the complete ordered batch.","tags":["Sync"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","required":["method","path"],"properties":{"id":{"type":"string"},"method":{"type":"string","enum":["GET","HEAD","POST","PUT","DELETE"]},"path":{"type":"string","example":"/files/file_id"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body":{}}}},"stopOnError":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Per-operation results","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}}}},"/api/v1/sync":{"post":{"operationId":"runV1SyncRound","summary":"Push mutations, then pull canonical changes in one round trip","description":"Designed for CLI, web workers, desktop, and mobile. Use If-Match per mutation; 412 results include the current revision and endpoint for conflict recovery.","tags":["Sync"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cursor"],"properties":{"cursor":{"oneOf":[{"type":"integer"},{"type":"string"}]},"mutations":{"type":"array","maxItems":25,"items":{"type":"object"}},"changeLimit":{"type":"integer","minimum":1,"maximum":500},"stopOnError":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Mutation results and ordered pull page","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"410":{"description":"Cursor expired; mutation results are included but the client must re-bootstrap","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/devices":{"get":{"operationId":"listV1Devices","summary":"List this account's registered sync devices","tags":["Sync"],"responses":{"200":{"description":"Registered devices","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"List this account's registered sync devices"},"post":{"operationId":"registerV1Device","summary":"Register a device for per-device availability","description":"Each installation registers once and stores its device ID. Per-file pin policy is written via /api/v1/devices/{id}/state and overrides the file's server-wide availability on that device only.","tags":["Sync"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"platform":{"type":"string","maxLength":40}}}}}},"responses":{"201":{"description":"Registered device","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}}}},"/api/v1/devices/{id}":{"get":{"operationId":"getV1Device","summary":"Read a device and its per-file availability overrides","description":"States list only explicit overrides; files without one follow the file's `availability` default (`cloud` maps to online-only, `cloud+local` to available).","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Device and state overrides","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Device not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteV1Device","summary":"Forget a device and its state overrides","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Device forgotten","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}}},"404":{"description":"Device not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Forget a device and its state overrides"}},"/api/v1/devices/{id}/state":{"put":{"operationId":"putV1DeviceStates","summary":"Write per-file availability for one device","description":"Bulk pin-policy write: `online-only` (placeholder, no bytes on the device), `available` (cached, evictable), or `pinned` (guaranteed local). `state: null` clears the override so the file follows its server-wide availability again. State changes appear on /api/v1/changes as `device` resources.","tags":["Sync"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["states"],"properties":{"states":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string"},"state":{"oneOf":[{"type":"string","enum":["online-only","available","pinned"]},{"type":"null"}]}}}}}}}}},"responses":{"200":{"description":"Per-entry results","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"404":{"description":"Device not found","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"listV1Webhooks","summary":"List webhook endpoints","tags":["Webhooks"],"responses":{"200":{"description":"Webhook endpoints","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"List webhook endpoints"},"post":{"operationId":"createV1Webhook","summary":"Create a signed HTTPS webhook","description":"The HMAC signing secret is returned once. Private, loopback, local, and DNS-rebinding targets are rejected.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["file.upsert","file.delete","folder.upsert","folder.delete"]}}}}}}},"responses":{"201":{"description":"Webhook and one-time signing secret","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"503":{"description":"Server signing secret is not configured","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}":{"patch":{"operationId":"updateV1Webhook","summary":"Update or pause a webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated webhook","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Update or pause a webhook"},"delete":{"operationId":"deleteV1Webhook","summary":"Delete a webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}},"description":"Delete a webhook"}},"/api/sandbox":{"get":{"operationId":"getPublicSandbox","summary":"Inspect the zero-auth non-mutating API sandbox","description":"Returns example operations and response shapes without accessing account data.","security":[],"tags":["API"],"responses":{"200":{"description":"Sandbox discovery","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}}}},"post":{"operationId":"simulatePublicSandboxRequest","summary":"Simulate an API request without mutation","description":"Echoes a proposed request and returns a deterministic simulated success response. It never reads or writes workspace data.","security":[],"tags":["API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method","path"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"body":{}}}}}},"responses":{"200":{"description":"Simulated response","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonObject"}}}},"400":{"description":"Invalid JSON request","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer"}},"API-Version":{"description":"Resolved API version","schema":{"type":"string","example":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}