{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"KeepFlash Agent API","version":"1.0.0","summary":"Authorize agents and connect them to KeepFlash over MCP.","description":"The public bootstrap API issues scoped Agent Access tokens through a device authorization flow. Use the resulting Bearer token with the MCP transport at /api/mcp. Product-internal browser APIs are intentionally not part of this public contract.","contact":{"url":"https://keepflash.com/en"},"license":{"name":"Proprietary","url":"https://keepflash.com/en/policies/terms-of-use"}},"servers":[{"url":"https://keepflash.com","description":"Production"}],"tags":[{"name":"Agent authorization","description":"Device-code authorization for Agent Access tokens."},{"name":"MCP","description":"Authenticated Model Context Protocol transport."}],"paths":{"/api/agent-access/device/code":{"post":{"operationId":"createAgentDeviceCode","summary":"Start device authorization","tags":["Agent authorization"],"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCodeRequest"}}}},"responses":{"200":{"description":"Device authorization created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCodeResponse"}}}},"400":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/agent-access/device/token":{"post":{"operationId":"pollAgentDeviceToken","summary":"Poll for an approved Agent Access token","description":"Poll no faster than the interval returned by the device-code operation. The authorization_pending and slow_down states are structured error responses.","tags":["Agent authorization"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenRequest"}}}},"responses":{"200":{"description":"Agent Access token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenResponse"}}}},"400":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/agent-access/current":{"delete":{"operationId":"revokeCurrentAgentToken","summary":"Revoke the current Agent Access token","tags":["Agent authorization"],"security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Token revoked or already inactive"},"401":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/mcp":{"post":{"operationId":"sendMcpMessage","summary":"Send a JSON-RPC message to the KeepFlash MCP server","description":"Implements the MCP Streamable HTTP transport. Initialize the MCP session before calling tools. Tool availability is constrained by the scopes approved during device authorization.","tags":["MCP"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC response or stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"openMcpTransport","summary":"Open the MCP Streamable HTTP transport","tags":["MCP"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"MCP transport response","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"closeMcpTransport","summary":"Close an MCP transport session","tags":["MCP"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"MCP session closed"},"401":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Structured error with a recovery hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"KeepFlash Agent Access token","description":"Token returned by the device-token operation."}},"schemas":{"ApiError":{"type":"object","additionalProperties":true,"required":["error","code","message","resolution"],"properties":{"error":{"type":"string","description":"Stable error identifier retained for OAuth-style client compatibility."},"code":{"type":"string","description":"Stable machine error code."},"message":{"type":"string","description":"Human-readable description of the failure."},"resolution":{"type":"string","description":"Concrete next step that may resolve the failure."}}},"DeviceCodeRequest":{"type":"object","additionalProperties":false,"properties":{"client_name":{"type":"string","minLength":1,"maxLength":80,"description":"Name shown to the user during authorization."}}},"DeviceCodeResponse":{"type":"object","additionalProperties":false,"required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"],"properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer","minimum":1},"interval":{"type":"integer","minimum":1}}},"DeviceTokenRequest":{"type":"object","additionalProperties":false,"required":["device_code"],"properties":{"device_code":{"type":"string","minLength":1,"maxLength":256}}},"DeviceTokenResponse":{"type":"object","additionalProperties":false,"required":["access_token","token_type","scope"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","const":"Bearer"},"scope":{"type":"string"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":["object","array","null"]}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":true,"error":{"type":["object","null"]}}}}}}