{"openapi":"3.1.0","info":{"title":"Blinko Cloud Agent and Extension API","version":"1.0.144","description":"Separate token-scoped APIs for agents and installed Apps. Agent tokens access user-approved Blinko resources; Extension OAuth tokens access only the installed App's declared capabilities and isolated data namespace."},"servers":[{"url":"http://api.blinko.space","description":"Blinko Cloud"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Authentication","description":"Validate and inspect an Agent Token."},{"name":"Notes","description":"Create, read, search, update, and trash Blinks and Notes."},{"name":"Tags","description":"Read and organize the user's tag tree."},{"name":"App Commands","description":"Agent-callable commands declared by installed Apps and constrained by host-owned context."},{"name":"Extension OAuth","description":"Authorization Code + S256 PKCE for installed Apps; separate from Agent tokens."},{"name":"Extension Data","description":"Manifest-declared AppEntity and AppState APIs, isolated by account and installation."},{"name":"Extension Assets","description":"Quota-bound AppEntity assets backed by governed Blinko storage."},{"name":"Extension Network","description":"Exact-domain outbound HTTPS with DNS, redirect, timeout, and response budgets."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Blinko Agent Token","description":"Paste the blk_ token created in Blinko Cloud settings."},"ExtensionBearer":{"type":"http","scheme":"bearer","bearerFormat":"Blinko Extension Access Token","description":"Short-lived blx_ token issued through Authorization Code + PKCE."}},"schemas":{},"parameters":{}},"paths":{"/oauth/extension/authorize":{"post":{"tags":["Extension OAuth"],"summary":"Create a session-approved PKCE authorization code","operationId":"authorizeExtension","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"installation_id":{"type":"string"},"target":{"type":"string","enum":["web","desktop","android","ios","browser"]},"redirect_uri":{"type":"string","format":"uri"},"audience":{"type":"string","format":"uri"},"code_challenge":{"type":"string"},"code_challenge_method":{"type":"string","enum":["S256"]}},"required":["installation_id","target","redirect_uri","audience","code_challenge","code_challenge_method"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"expires_at":{"type":"string"},"scope":{"type":"string"}},"required":["code","expires_at","scope"]}}}},"400":{"description":"Invalid binding","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"User session required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/oauth/extension/token":{"post":{"tags":["Extension OAuth"],"summary":"Exchange or rotate an Extension token","operationId":"exchangeExtensionToken","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code"]},"code":{"type":"string"},"code_verifier":{"type":"string"},"client_id":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"audience":{"type":"string","format":"uri"}},"required":["grant_type","code","code_verifier","client_id","redirect_uri","audience"]},{"type":"object","properties":{"grant_type":{"type":"string","enum":["refresh_token"]},"refresh_token":{"type":"string"},"audience":{"type":"string","format":"uri"}},"required":["grant_type","refresh_token","audience"]}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"scope":{"type":"string"}},"required":["access_token","refresh_token","token_type","expires_in","scope"]}}}},"400":{"description":"Invalid or replayed grant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities":{"post":{"tags":["Extension Data"],"summary":"Create an App-owned entity","operationId":"createAppEntity","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typeKey":{"type":"string"},"data":{},"idempotencyKey":{"type":"string"}},"required":["typeKey"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities/query":{"post":{"tags":["Extension Data"],"summary":"Query App-owned entities with signed keyset pagination","operationId":"listAppEntities","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typeKey":{"type":"string"},"status":{"type":"string","enum":["active","trashed","all"],"default":"active"},"filters":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":8,"default":[]},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"]},"cursor":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},"required":["typeKey"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities/{id}":{"patch":{"tags":["Extension Data"],"summary":"Update an entity with optimistic concurrency","operationId":"updateAppEntity","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{},"baseVersion":{"type":"integer","minimum":1}},"required":["baseVersion"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Version conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities/{id}/trash":{"post":{"tags":["Extension Data"],"summary":"Move an entity to trash","operationId":"trashAppEntity","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseVersion":{"type":"integer","minimum":1}},"required":["baseVersion"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Version conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities/{id}/restore":{"post":{"tags":["Extension Data"],"summary":"Restore an entity from trash","operationId":"restoreAppEntity","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseVersion":{"type":"integer","minimum":1}},"required":["baseVersion"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Version conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/state/{namespace}/{key}":{"get":{"tags":["Extension Data"],"summary":"Read namespaced App state","operationId":"getAppState","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","enum":["settings","sync","cache"]},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string"},"required":true,"name":"key","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}},"put":{"tags":["Extension Data"],"summary":"Create or update namespaced App state","operationId":"putAppState","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","enum":["settings","sync","cache"]},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string"},"required":true,"name":"key","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{},"baseVersion":{"type":"integer","minimum":1},"ttlSeconds":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Version conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}},"delete":{"tags":["Extension Data"],"summary":"Delete namespaced App state","operationId":"deleteAppState","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","enum":["settings","sync","cache"]},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string"},"required":true,"name":"key","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"baseVersion","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Version conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/assets":{"post":{"tags":["Extension Assets"],"summary":"Upload and associate a bounded App asset","operationId":"uploadAppAsset","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"x-entity-id","in":"header"},{"schema":{"type":"string"},"required":true,"name":"x-file-name","in":"header"}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"413":{"description":"Asset exceeds a byte or quota budget","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/assets/import":{"post":{"tags":["Extension Assets"],"summary":"Import a remote asset through the authorized network broker","operationId":"importAppAsset","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string"},"url":{"type":"string","format":"uri"},"fileName":{"type":"string"}},"required":["entityId","url"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"413":{"description":"Response exceeds a byte budget","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/entities/{id}/assets":{"get":{"tags":["Extension Assets"],"summary":"List assets associated with an entity","operationId":"listAppEntityAssets","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":100}},"required":["items"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/assets/{id}/content":{"get":{"tags":["Extension Assets"],"summary":"Read an authorized asset handle","operationId":"readAppAsset","security":[{"ExtensionBearer":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Asset bytes"},"302":{"description":"Short-lived object-store redirect"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/network/fetch":{"post":{"tags":["Extension Network"],"summary":"Fetch bounded text or JSON through the SSRF-safe network broker","operationId":"fetchExtensionNetwork","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"responseType":{"type":"string","enum":["text","json"]}},"required":["url","responseType"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"413":{"description":"Response exceeds a byte budget","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"App network budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/extensions/data/content/extract":{"post":{"tags":["Extension Network"],"summary":"Extract bounded Markdown and image candidates from an authorized web page","operationId":"extractExtensionWebContent","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"413":{"description":"Extracted content exceeds the output budget","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Readable content was not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"App network budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/extensions/data/ai/generate":{"post":{"tags":["Extension AI"],"summary":"Generate bounded text through the account AI provider","operationId":"generateExtensionText","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":16000},"system":{"type":"string","maxLength":4000},"maxOutputTokens":{"type":"integer","minimum":64,"maximum":4096}},"required":["prompt"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"AI quota or concurrency limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"503":{"description":"AI provider is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/extensions/data/ai/generate-stream":{"post":{"tags":["Extension AI"],"summary":"Stream bounded text through the account AI provider","operationId":"streamExtensionText","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":16000},"system":{"type":"string","maxLength":4000},"maxOutputTokens":{"type":"integer","minimum":64,"maximum":4096}},"required":["prompt"]}}}},"responses":{"200":{"description":"Newline-delimited text-delta events followed by one done event"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"AI quota or concurrency limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"503":{"description":"AI provider is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/extensions/data/ai/availability":{"post":{"tags":["Extension AI"],"summary":"Check whether the account has a usable model for an App AI feature","operationId":"getExtensionAiAvailability","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"feature":{"type":"string","enum":["chat"]}},"required":["feature"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"feature":{"type":"string","enum":["chat"]},"available":{"type":"boolean"}},"required":["feature","available"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/extensions/data/companion/activity":{"post":{"tags":["Extension Data"],"summary":"Record a bounded companion activity for an App-owned entity","operationId":"recordAppCompanionActivity","security":[{"ExtensionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string"},"occurrenceKey":{"type":"string"}},"required":["entityId","occurrenceKey"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request budget exceeded; retry after the advertised delay","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limit"]},"retryAfterSeconds":{"type":"integer","minimum":1}},"required":["error","retryAfterSeconds"]}}}}}}},"/api/agent/whoami":{"get":{"tags":["Authentication"],"summary":"Inspect the current token","operationId":"agentWhoami","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"project":{"type":["string","null"]}},"required":["userId","scopes","project"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/apps/commands":{"get":{"tags":["App Commands"],"summary":"List enabled App commands callable by an agent","operationId":"listAppCommands","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["web","desktop","android","ios","browser"]},"required":true,"name":"target","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/apps/commands/{key}/prepare":{"post":{"tags":["App Commands"],"summary":"Prepare a capability-checked App command invocation","operationId":"prepareAppCommand","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"key","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","enum":["web","desktop","android","ios","browser"]},"context":{}},"required":["target"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Command is not callable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/note":{"get":{"tags":["Notes"],"summary":"List notes and blinks","operationId":"listNotes","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["BLINK","NOTE"],"example":"BLINK"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","example":"work/ideas"},"required":false,"name":"tagPath","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"false"},"required":false,"name":"archived","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"false"},"required":false,"name":"trashed","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"tags":["Notes"],"summary":"Create a Blinko","operationId":"createNote","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"default":"My first Blinko from the API","example":"My first Blinko from the API"},"type":{"type":"string","enum":["BLINK","NOTE"],"default":"BLINK"},"title":{"type":"string","example":"API test"},"tagPaths":{"type":"array","items":{"type":"string"},"example":["api/test"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/note/search":{"get":{"tags":["Notes"],"summary":"Search notes","operationId":"searchNotes","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","default":"Blinko","example":"Blinko"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["BLINK","NOTE"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/note/{id}":{"get":{"tags":["Notes"],"summary":"Get a note","operationId":"getNote","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["Notes"],"summary":"Update a note","operationId":"updateNote","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","example":"Updated from the API explorer"},"title":{"type":["string","null"]},"baseVersion":{"type":"integer","minimum":0,"example":0},"tagPaths":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["Notes"],"summary":"Move a note to trash","operationId":"trashNote","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"clx_note_id"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/tag":{"get":{"tags":["Tags"],"summary":"List the tag tree","operationId":"listTags","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Token is missing the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}}},"webhooks":{}}