{"openapi":"3.1.0","info":{"title":"txt-fil.es API","version":"1.0.0","description":"The public txt-fil.es REST contract for remote notes and attachments. Attachment bytes stay in the user's private dots blob while txt manages their workspace metadata and links. Listings are metadata-only and file GETs support ETag / If-None-Match (304). New integrations use /api/v1 and follow the published versioning and deprecation policy.","contact":{"url":"https://api.n0t.es/contact"}},"externalDocs":{"description":"txt-fil.es developer portal, quickstart, authentication, webhooks, and deprecation policy","url":"https://api.n0t.es/developers"},"servers":[{"url":"https://api.n0t.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","code:read":"Allows code read operations","code:write":"Allows code write 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","description":"Normalized extension, or bin when extensionless"},"storage":{"type":"string","enum":["inline","dots"]},"contentType":{"type":["string","null"]},"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","null"],"description":"Null for dots-backed attachments; download through raw"},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}},"type":{"type":"string"},"storage":{"type":"string","enum":["inline","dots"]},"contentType":{"type":["string","null"]},"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/identities":{"get":{"operationId":"listAccountIdentities","summary":"List connected dots users and the active identity for this credential","tags":["Identity"],"responses":{"200":{"description":"Account, active identity, groups, and connected dots users","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 connected dots users and the active identity for this credential"},"patch":{"operationId":"switchAccountIdentity","summary":"Switch the active dots user for this credential only","tags":["Identity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identity"],"properties":{"identity":{"type":"string","description":"Username, immutable identity ID, subject, or 1-based list number"}}}}}},"responses":{"200":{"description":"Active identity changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Identity is not connected to this account","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Switch the active dots user for this credential only"}},"/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, rename, or move a file","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, rename, or move a file"},"delete":{"operationId":"trashFile","summary":"Move a file to recoverable trash","description":"Removes the file from normal views immediately while retaining it for at least 30 days. Use restore_note during the retention window; permanent purge is blocked until the window has elapsed.","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File moved to 30-day recoverable trash","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"trashed":{"type":"string"},"retentionDays":{"type":"integer","const":30}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"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 or already trashed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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/files/{id}/raw":{"get":{"operationId":"getFileRaw","summary":"Download raw file bytes (no JSON)","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw bytes with the file's stored Content-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/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":"Download raw file bytes (no JSON)"},"put":{"operationId":"replaceFileBytes","summary":"Replace bytes, retaining file ID, history and live links","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"ETag read from the current file. Wildcards are not accepted for byte replacements."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"428":{"description":"Missing If-Match","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Replace bytes, retaining file ID, history and live links"},"head":{"operationId":"statFileBytes","summary":"Read byte metadata without downloading","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Read byte metadata without downloading"}},"/api/me/files/upload":{"post":{"operationId":"uploadFileBytes","summary":"Upload an attachment to the user's private dots blob","tags":["Files"],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","maxLength":240}},{"name":"folderId","in":"query","schema":{"type":"string"}},{"name":"context","in":"query","schema":{"type":"string","maxLength":4000}},{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string"}}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","maxLength":104857600}}}},"responses":{"201":{"description":"Attachment uploaded","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 reconnection 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"}}}},"413":{"description":"Upload exceeds 100 MB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload an attachment to the user's private dots blob"}},"/api/me/files/import":{"post":{"operationId":"importFileFromUrl","summary":"Import a public HTTPS resource into the user's private dots blob","description":"Fetches one public HTTPS URL without redirects, blocks private-network destinations, enforces a 25 MB limit, and creates a manageable txt file record.","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"name":{"type":"string","maxLength":240},"folderId":{"type":["string","null"]},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Remote file imported","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 URL, filename, folder, or 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"}}}},"401":{"description":"Unauthorized or dots reconnection 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"}}}},"413":{"description":"Remote file exceeds 25 MB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Remote source or dots storage 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/files/{id}/share":{"post":{"operationId":"shareFileTemporarily","summary":"Mint a short-lived blob.f-il.es attachment URL","description":"Call only after the user explicitly asks to share this attachment. The opaque URL streams through txt without exposing its dots storage URL or key.","tags":["Files","Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expiresIn":{"type":"integer","minimum":60,"maximum":300,"default":300}}}}}},"responses":{"200":{"description":"Temporary blob.f-il.es URL and expiration","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 reconnection 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"}}}},"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"}}}},"409":{"description":"File is an inline text 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/Error"}}}}}}},"/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/v1/publication-subscriptions":{"get":{"operationId":"listPublicationSubscriptions","summary":"List the current identity's publication subscriptions","tags":["Publications"],"responses":{"200":{"description":"Active subscriptions with canonical pubs.li URLs","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 the current identity's publication subscriptions"},"post":{"operationId":"setPublicationSubscription","summary":"Subscribe or unsubscribe from a publication","description":"CLI and agent callers must obtain human approval before changing this public relationship.","tags":["Publications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","active"],"properties":{"slug":{"type":"string"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Subscription state changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Publication 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":{"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 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 folder share links"},"post":{"operationId":"createFolderShare","summary":"Create a public or password-protected 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},"password":{"type":"string","maxLength":1024,"description":"Optional password. Sent in the request body and stored only as a salted scrypt hash."},"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 or password-protected 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/analytics":{"get":{"operationId":"getShareLinkStats","summary":"Read lifetime views/clicks for an owned share","description":"Returns Dub click totals and lastClicked for the share's common tracking key. Both short and named URLs use this total. Stats are private to the owner; unavailable data returns a distinct status with null counts.","tags":["Shares"],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stats: status (ready, disabled, unavailable), clicks, lastClicked, checkedAt","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Sign in 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"}}}},"404":{"description":"Share not owned 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"}}}},"429":{"description":"Refresh limit reached","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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/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. Every share has a compact random txt.mn URL. Supply name to add a chosen alias and linkStyle to select short or named. 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},"linkStyle":{"type":"string","enum":["short","named"],"default":"short"},"name":{"type":"string","maxLength":64,"description":"Optional available lowercase name"}}}}}},"responses":{"200":{"description":"Copy-ready txt.mn publicUrl, shortUrl, optional namedUrl, separate tracking descriptor, 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"}}}}}},"patch":{"operationId":"updateShareLink","summary":"Change an owned share URL without rotating access or its password","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"linkStyle":{"type":"string","enum":["short","named"]},"name":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"Updated link addresses","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 or reserved name","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"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"}}}},"409":{"description":"Name already taken","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Change an owned share URL without rotating access or its password"},"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 file-aware, reviewable rewrite or document transform","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":100000},"action":{"type":"string","enum":["improve","fix","shorter","longer","formal","casual","custom"]},"customPrompt":{"type":"string","maxLength":4000},"fileName":{"type":"string","maxLength":255},"scope":{"type":"string","enum":["selection","document"],"default":"selection"},"targetFormat":{"type":"string","enum":["preserve","markdown","plain-text","html","json","yaml","mermaid","fountain"]}}}}}},"responses":{"200":{"description":"Suggestion plus provider, model, engine, output format, scope, and 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"}}}},"413":{"description":"Selection or document exceeds the scope-specific input limit","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 file-aware, reviewable rewrite or document transform"}},"/api/me/transcriptions":{"post":{"operationId":"transcribeHandwrittenNote","summary":"Transcribe an uploaded or remote handwritten-note image as text or a synced 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, WebP, or HEIC; 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","image/heic","image/heif"]},"mode":{"type":"string","enum":["structured","verbatim","diagram"],"default":"structured"},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"],"default":"md"},"folderId":{"type":["string","null"]},"output":{"type":"string","enum":["text","file"],"default":"file"}},"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","diagram"]},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"]},"folderId":{"type":["string","null"]},"output":{"type":"string","enum":["text","file"]}}}}}},"responses":{"200":{"description":"Transcription text 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"}}}},"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/me/artifacts":{"post":{"operationId":"renderArtifact","summary":"Render txt files into a deployable static artifact","description":"Creates a validated standalone HTML file and a txt.deploy/v1 handoff manifest. Plain html mode is deterministic; site mode or an explicit prompt uses the FX artifact worker. Rendering does not perform an external deployment.","tags":["Files","AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceFileId"],"properties":{"sourceFileId":{"type":"string"},"contextFileIds":{"type":"array","maxItems":8,"items":{"type":"string"}},"designFileIds":{"type":"array","maxItems":8,"items":{"type":"string"},"description":"Design-skill files applied as design guidance"},"designFolderId":{"type":"string","description":"Design-skill folder expanded recursively within the shared eight-file limit"},"mode":{"type":"string","enum":["html","site"],"default":"html"},"prompt":{"type":"string","maxLength":8000},"model":{"type":"string","maxLength":128,"description":"Allowlisted provider/model ID from GET /api/v1/artifacts/models; FX/site only"},"outputName":{"type":"string","maxLength":255},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Saved HTML artifact and txt.deploy/v1 manifest","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 source 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"}}}},"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":"Prompt assistance requires ai:use","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Rendering or sandbox validation 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/artifacts/models":{"get":{"operationId":"listFxModels","summary":"List deployment-approved FX models","description":"Returns the provider/model IDs accepted by FX rendering and identifies the default used when model is omitted.","tags":["AI"],"responses":{"200":{"description":"FX model catalog","content":{"application/json":{"schema":{"type":"object","required":["defaultModel","models"],"properties":{"defaultModel":{"type":"string"},"models":{"type":"array","items":{"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","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"}}}}}}},"/api/v1/theme":{"get":{"operationId":"getV1Theme","summary":"Resolve global, account, group, folder and note appearance","description":"Requires files:read. Returns catalog, catalog revision, account and target assignments with revisions, inherited and effective portable tokens, and ordered lineage. Groups apply alphabetically (then by ID), followed by folders from outermost to innermost, then the note. Folder and group writes require ownership. Clients ignore unsupported components and preserve editing state when refreshing themes.","tags":["Themes"],"parameters":[{"name":"fileId","in":"query","required":false,"schema":{"type":"string"},"description":"Choose at most one of fileId, folderId, groupId; omit all for the account default. Notes require read access for GET and write access for PUT."},{"name":"folderId","in":"query","required":false,"schema":{"type":"string"},"description":"Owned folder or group. Choose at most one target ID."},{"name":"groupId","in":"query","required":false,"schema":{"type":"string"},"description":"Owned folder or group. Choose at most one target ID."}],"responses":{"200":{"description":"Resolved theme state","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Target not accessible","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"setV1Theme","summary":"Save account, group, folder or note appearance","description":"Requires files:write. Send the revision from GET. A named theme replaces the inherited theme; individual overrides apply last. themeId:null with empty overrides restores inheritance. Global publishing is restricted to allowlisted browser administrators at /api/admin/themes.","tags":["Themes"],"parameters":[{"name":"fileId","in":"query","required":false,"schema":{"type":"string"},"description":"Choose at most one of fileId, folderId, groupId; omit all for the account default. Notes require read access for GET and write access for PUT."},{"name":"folderId","in":"query","required":false,"schema":{"type":"string"},"description":"Owned folder or group. Choose at most one target ID."},{"name":"groupId","in":"query","required":false,"schema":{"type":"string"},"description":"Owned folder or group. Choose at most one target ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["themeId","overrides","revision"],"properties":{"themeId":{"type":["string","null"]},"revision":{"type":"integer","minimum":0},"overrides":{"type":"object","additionalProperties":false,"properties":{"interfaceStyle":{"type":"string","enum":["minimal","sacred","aim","aqua","windows95","drawn"]},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"surface":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"foreground":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"muted":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"border":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accentText":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"selection":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"uiFont":{"type":"string","enum":["pixel","sans","mono","serif","pen"]},"editorFont":{"type":"string","enum":["pixel","sans","mono","serif","pen"]},"uiFontSize":{"type":"number","minimum":11,"maximum":24},"editorFontSize":{"type":"number","minimum":12,"maximum":40},"titleFontSize":{"type":"number","minimum":14,"maximum":40},"lineHeight":{"type":"number","minimum":1.2,"maximum":2.4},"sidebarWidth":{"type":"number","minimum":160,"maximum":420},"panelWidth":{"type":"number","minimum":240,"maximum":600},"editorWidth":{"type":"number","minimum":360,"maximum":1600},"editorPadding":{"type":"number","minimum":8,"maximum":80},"headerHeight":{"type":"number","minimum":44,"maximum":96},"rowHeight":{"type":"number","minimum":28,"maximum":64},"statusHeight":{"type":"number","minimum":28,"maximum":64},"gap":{"type":"number","minimum":4,"maximum":24},"radius":{"type":"number","minimum":0,"maximum":24},"borderWidth":{"type":"number","minimum":0,"maximum":3},"showSidebar":{"type":"boolean"},"showWritingTools":{"type":"boolean"},"showStatusBar":{"type":"boolean"},"showModeSwitch":{"type":"boolean"},"showWordCount":{"type":"boolean"},"showMetadata":{"type":"boolean"},"showVersions":{"type":"boolean"},"showComments":{"type":"boolean"},"showSuggestions":{"type":"boolean"},"showBrain":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Saved and resolved theme state","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 theme","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"403":{"description":"Read-only 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/Error"}}}},"404":{"description":"Target not accessible","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Revision conflict: reload before saving","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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/themes":{"get":{"operationId":"getThemeCatalog","summary":"Read the global theme library","security":[],"tags":["Themes"],"responses":{"200":{"description":"Version 1 theme catalog and revision","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Read the global theme library"}},"/api/me/files/{id}/links":{"get":{"operationId":"listFileLinks","summary":"List link policies and effective states; secret URLs are shown only on creation","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 link policies and effective states; secret URLs are shown only on creation"},"post":{"operationId":"createFileLink","summary":"Create a live or immutable snapshot download link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["live","snapshot"],"default":"live"},"label":{"type":"string","maxLength":120},"password":{"type":"string","maxLength":1024},"expiresAt":{"type":["string","null"],"format":"date-time"},"maxDownloads":{"type":["integer","null"],"minimum":1}},"required":[]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Link URL; copy now, as only its hash is stored","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 live or immutable snapshot download link"},"patch":{"operationId":"setFileLinkState","summary":"Pause, resume or permanently revoke a link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string"},"state":{"type":"string","enum":["active","paused","revoked"]}},"required":["linkId","state"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Pause, resume or permanently revoke a link"}},"/api/me/files/{id}/stored-versions":{"get":{"operationId":"listStoredFileVersions","summary":"List immutable versions of a private stored file","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 immutable versions of a private stored file"},"post":{"operationId":"restoreStoredFileVersion","summary":"Restore stored bytes as a new revision","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"ETag read from the current file. Wildcards are not accepted for byte replacements."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"type":"string"}},"required":["versionId"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Restore stored bytes as a new revision"}},"/api/me/files/trash":{"get":{"operationId":"listTrashedFiles","summary":"List the signed-in owner’s recoverable files","tags":["Files"],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 the signed-in owner’s recoverable files"},"post":{"operationId":"restoreTrashedFile","summary":"Restore a file from trash","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string"}},"required":["fileId"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Restore a file from trash"}},"/api/me/files/uploads":{"post":{"operationId":"beginFileUpload","summary":"Start a private upload in 4 MiB chunks; expires after 24 hours","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":104857600},"contentType":{"type":"string"},"folderId":{"type":["string","null"]},"fileId":{"type":"string","description":"Existing file ID for replacement"},"revision":{"type":"integer","description":"Required current revision for replacement"}},"required":["name","size"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload ID, chunkSize and part count","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Start a private upload in 4 MiB chunks; expires after 24 hours"}},"/api/me/files/uploads/{uploadId}":{"put":{"operationId":"putFileUploadChunk","summary":"Upload one numbered chunk; identical retries are idempotent","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},{"name":"part","in":"query","required":true,"schema":{"type":"integer","minimum":0}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload one numbered chunk; identical retries are idempotent"},"post":{"operationId":"finishFileUpload","summary":"Verify and assemble all chunks, then commit to private storage","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 assemble all chunks, then commit to private storage"},"delete":{"operationId":"cancelFileUpload","summary":"Cancel an incomplete upload and clean temporary chunks","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Cancel an incomplete upload and clean temporary chunks"}},"/api/file-links/{token}":{"get":{"operationId":"readFileLink","summary":"Resolve a file link; download=1 atomically consumes one download","tags":["Shares"],"security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"X-Txt-Share-Password","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"410":{"description":"Paused, revoked, expired or exhausted","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 a file link; download=1 atomically consumes one download"}},"/api/v1/files/{id}/links":{"get":{"operationId":"v1ListFileLinks","summary":"List link policies and effective states; secret URLs are shown only on creation","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 link policies and effective states; secret URLs are shown only on creation"},"post":{"operationId":"v1CreateFileLink","summary":"Create a live or immutable snapshot download link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["live","snapshot"],"default":"live"},"label":{"type":"string","maxLength":120},"password":{"type":"string","maxLength":1024},"expiresAt":{"type":["string","null"],"format":"date-time"},"maxDownloads":{"type":["integer","null"],"minimum":1}},"required":[]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Link URL; copy now, as only its hash is stored","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 live or immutable snapshot download link"},"patch":{"operationId":"v1SetFileLinkState","summary":"Pause, resume or permanently revoke a link","tags":["Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string"},"state":{"type":"string","enum":["active","paused","revoked"]}},"required":["linkId","state"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Pause, resume or permanently revoke a link"}},"/api/v1/files/{id}/stored-versions":{"get":{"operationId":"v1ListStoredFileVersions","summary":"List immutable versions of a private stored file","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 immutable versions of a private stored file"},"post":{"operationId":"v1RestoreStoredFileVersion","summary":"Restore stored bytes as a new revision","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"ETag read from the current file. Wildcards are not accepted for byte replacements."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"type":"string"}},"required":["versionId"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Restore stored bytes as a new revision"}},"/api/v1/files/trash":{"get":{"operationId":"v1ListTrashedFiles","summary":"List the signed-in owner’s recoverable files","tags":["Files"],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 the signed-in owner’s recoverable files"},"post":{"operationId":"v1RestoreTrashedFile","summary":"Restore a file from trash","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string"}},"required":["fileId"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Restore a file from trash"}},"/api/v1/files/uploads":{"post":{"operationId":"v1BeginFileUpload","summary":"Start a private upload in 4 MiB chunks; expires after 24 hours","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":104857600},"contentType":{"type":"string"},"folderId":{"type":["string","null"]},"fileId":{"type":"string","description":"Existing file ID for replacement"},"revision":{"type":"integer","description":"Required current revision for replacement"}},"required":["name","size"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload ID, chunkSize and part count","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Start a private upload in 4 MiB chunks; expires after 24 hours"}},"/api/v1/files/uploads/{uploadId}":{"put":{"operationId":"v1PutFileUploadChunk","summary":"Upload one numbered chunk; identical retries are idempotent","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},{"name":"part","in":"query","required":true,"schema":{"type":"integer","minimum":0}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload one numbered chunk; identical retries are idempotent"},"post":{"operationId":"v1FinishFileUpload","summary":"Verify and assemble all chunks, then commit to private storage","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 assemble all chunks, then commit to private storage"},"delete":{"operationId":"v1CancelFileUpload","summary":"Cancel an incomplete upload and clean temporary chunks","tags":["Files"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Cancel an incomplete upload and clean temporary chunks"}},"/api/v1/identities":{"get":{"operationId":"v1ListAccountIdentities","summary":"List connected dots users and the active identity for this credential","tags":["Identity"],"responses":{"200":{"description":"Account, active identity, groups, and connected dots users","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 connected dots users and the active identity for this credential"},"patch":{"operationId":"v1SwitchAccountIdentity","summary":"Switch the active dots user for this credential only","tags":["Identity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identity"],"properties":{"identity":{"type":"string","description":"Username, immutable identity ID, subject, or 1-based list number"}}}}}},"responses":{"200":{"description":"Active identity changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Identity is not connected to this account","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Switch the active dots user for this credential only"}},"/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","description":"Normalized extension such as md, pdf, png, or mp3"}},{"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, rename, or move a file","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, rename, or move a file"},"delete":{"operationId":"v1TrashFile","summary":"Move a file to recoverable trash","description":"Removes the file from normal views immediately while retaining it for at least 30 days. Use restore_note during the retention window; permanent purge is blocked until the window has elapsed.","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File moved to 30-day recoverable trash","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"trashed":{"type":"string"},"retentionDays":{"type":"integer","const":30}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"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 or already trashed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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/{id}/raw":{"get":{"operationId":"v1GetFileRaw","summary":"Download raw file bytes (no JSON)","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw bytes with the file's stored Content-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/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":"Download raw file bytes (no JSON)"},"put":{"operationId":"v1ReplaceFileBytes","summary":"Replace bytes, retaining file ID, history and live links","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"ETag read from the current file. Wildcards are not accepted for byte replacements."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"428":{"description":"Missing If-Match","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Replace bytes, retaining file ID, history and live links"},"head":{"operationId":"v1StatFileBytes","summary":"Read byte metadata without downloading","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 input","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"404":{"description":"Resource 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"}}}},"409":{"description":"Conflict or incomplete upload","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"412":{"description":"File revision changed","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Read byte metadata without downloading"}},"/api/v1/files/upload":{"post":{"operationId":"v1UploadFileBytes","summary":"Upload an attachment to the user's private dots blob","tags":["Files"],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","maxLength":240}},{"name":"folderId","in":"query","schema":{"type":"string"}},{"name":"context","in":"query","schema":{"type":"string","maxLength":4000}},{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string"}}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","maxLength":104857600}}}},"responses":{"201":{"description":"Attachment uploaded","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 reconnection 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"}}}},"413":{"description":"Upload exceeds 100 MB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Upload an attachment to the user's private dots blob"}},"/api/v1/files/import":{"post":{"operationId":"v1ImportFileFromUrl","summary":"Import a public HTTPS resource into the user's private dots blob","description":"Fetches one public HTTPS URL without redirects, blocks private-network destinations, enforces a 25 MB limit, and creates a manageable txt file record.","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"name":{"type":"string","maxLength":240},"folderId":{"type":["string","null"]},"context":{"type":"string","maxLength":4000},"tags":{"type":"array","maxItems":16,"items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Remote file imported","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 URL, filename, folder, or 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"}}}},"401":{"description":"Unauthorized or dots reconnection 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"}}}},"413":{"description":"Remote file exceeds 25 MB","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Remote source or dots storage 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/v1/files/{id}/share":{"post":{"operationId":"v1ShareFileTemporarily","summary":"Mint a short-lived blob.f-il.es attachment URL","description":"Call only after the user explicitly asks to share this attachment. The opaque URL streams through txt without exposing its dots storage URL or key.","tags":["Files","Shares"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expiresIn":{"type":"integer","minimum":60,"maximum":300,"default":300}}}}}},"responses":{"200":{"description":"Temporary blob.f-il.es URL and expiration","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 reconnection 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"}}}},"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"}}}},"409":{"description":"File is an inline text 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/Error"}}}}}}},"/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 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 folder share links"},"post":{"operationId":"v1CreateFolderShare","summary":"Create a public or password-protected 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},"password":{"type":"string","maxLength":1024,"description":"Optional password. Sent in the request body and stored only as a salted scrypt hash."},"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 or password-protected 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. Every share has a compact random txt.mn URL. Supply name to add a chosen alias and linkStyle to select short or named. 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},"linkStyle":{"type":"string","enum":["short","named"],"default":"short"},"name":{"type":"string","maxLength":64,"description":"Optional available lowercase name"}}}}}},"responses":{"200":{"description":"Copy-ready txt.mn publicUrl, shortUrl, optional namedUrl, separate tracking descriptor, 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"}}}}}},"patch":{"operationId":"v1UpdateShareLink","summary":"Change an owned share URL without rotating access or its password","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"linkStyle":{"type":"string","enum":["short","named"]},"name":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"Updated link addresses","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 or reserved name","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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"}}}},"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"}}}},"409":{"description":"Name already taken","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Change an owned share URL without rotating access or its password"},"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/shares/analytics":{"get":{"operationId":"v1GetShareLinkStats","summary":"Read lifetime views/clicks for an owned share","description":"Returns Dub click totals and lastClicked for the share's common tracking key. Both short and named URLs use this total. Stats are private to the owner; unavailable data returns a distinct status with null counts.","tags":["Shares"],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stats: status (ready, disabled, unavailable), clicks, lastClicked, checkedAt","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Sign in 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"}}}},"404":{"description":"Share not owned 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"}}}},"429":{"description":"Refresh limit reached","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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/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 file-aware, reviewable rewrite or document transform","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":100000},"action":{"type":"string","enum":["improve","fix","shorter","longer","formal","casual","custom"]},"customPrompt":{"type":"string","maxLength":4000},"fileName":{"type":"string","maxLength":255},"scope":{"type":"string","enum":["selection","document"],"default":"selection"},"targetFormat":{"type":"string","enum":["preserve","markdown","plain-text","html","json","yaml","mermaid","fountain"]}}}}}},"responses":{"200":{"description":"Suggestion plus provider, model, engine, output format, scope, and 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"}}}},"413":{"description":"Selection or document exceeds the scope-specific input limit","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 file-aware, reviewable rewrite or document transform"}},"/api/v1/transcriptions":{"post":{"operationId":"v1TranscribeHandwrittenNote","summary":"Transcribe an uploaded or remote handwritten-note image as text or a synced 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, WebP, or HEIC; 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","image/heic","image/heif"]},"mode":{"type":"string","enum":["structured","verbatim","diagram"],"default":"structured"},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"],"default":"md"},"folderId":{"type":["string","null"]},"output":{"type":"string","enum":["text","file"],"default":"file"}},"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","diagram"]},"prompt":{"type":"string","maxLength":2000},"name":{"type":"string","maxLength":240},"fileType":{"type":"string","enum":["txt","md"]},"folderId":{"type":["string","null"]},"output":{"type":"string","enum":["text","file"]}}}}}},"responses":{"200":{"description":"Transcription text 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"}}}},"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/artifacts":{"post":{"operationId":"v1RenderArtifact","summary":"Render txt files into a deployable static artifact","description":"Creates a validated standalone HTML file and a txt.deploy/v1 handoff manifest. Plain html mode is deterministic; site mode or an explicit prompt uses the FX artifact worker. Rendering does not perform an external deployment.","tags":["Files","AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceFileId"],"properties":{"sourceFileId":{"type":"string"},"contextFileIds":{"type":"array","maxItems":8,"items":{"type":"string"}},"designFileIds":{"type":"array","maxItems":8,"items":{"type":"string"},"description":"Design-skill files applied as design guidance"},"designFolderId":{"type":"string","description":"Design-skill folder expanded recursively within the shared eight-file limit"},"mode":{"type":"string","enum":["html","site"],"default":"html"},"prompt":{"type":"string","maxLength":8000},"model":{"type":"string","maxLength":128,"description":"Allowlisted provider/model ID from GET /api/v1/artifacts/models; FX/site only"},"outputName":{"type":"string","maxLength":255},"folderId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Saved HTML artifact and txt.deploy/v1 manifest","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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 source 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"}}}},"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":"Prompt assistance requires ai:use","headers":{"X-Request-ID":{"description":"Request correlation identifier","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Maximum requests in the current policy window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the 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":"Rendering or sandbox validation 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/v1/artifacts/models":{"get":{"operationId":"v1ListFxModels","summary":"List deployment-approved FX models","description":"Returns the provider/model IDs accepted by FX rendering and identifies the default used when model is omitted.","tags":["AI"],"responses":{"200":{"description":"FX model catalog","content":{"application/json":{"schema":{"type":"object","required":["defaultModel","models"],"properties":{"defaultModel":{"type":"string"},"models":{"type":"array","items":{"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","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"}}}}}}},"/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"}}}}}}}}}