{"openapi":"3.0.0","info":{"version":"1.0.0","title":"Pokke API","description":"API for Pokke bookmarking service"},"servers":[{"url":"https://api.pokke.femto-cloud.com","description":"Production server"}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok","description":"Health status"},"timestamp":{"type":"string","example":"2024-01-01T00:00:00.000Z","description":"Current timestamp"}},"required":["status","timestamp"]},"CreateBookmarkResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"normalizedUrl":{"type":"string"},"originalUrl":{"type":"string"},"workspaceId":{"type":"string","format":"uuid"},"createdAt":{"type":"string"}},"required":["id","normalizedUrl","originalUrl","workspaceId","createdAt"]},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"NotFoundResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"InternalErrorResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"CreateBookmarkRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com"},"workspaceId":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000"},"metadata":{"$ref":"#/components/schemas/ManualBookmarkMetadataRequest"}},"required":["url","workspaceId"]},"ManualBookmarkMetadataRequest":{"type":"object","properties":{"source":{"type":"string","enum":["manual_input"],"description":"Indicates manual metadata input"},"title":{"type":"string"},"description":{"type":"string"},"ogImageUrl":{"type":"string","format":"uri"},"faviconUrl":{"type":"string","format":"uri"},"rawMetadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["source"]},"ListBookmarksResponse":{"type":"object","properties":{"bookmarks":{"type":"array","items":{"$ref":"#/components/schemas/Bookmark"}},"totalCount":{"type":"number"}},"required":["bookmarks"]},"Bookmark":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"createdBy":{"type":"string","format":"uuid"},"normalizedUrl":{"type":"string"},"originalUrl":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"aiSummary":{"type":"string"},"aiSummaryGeneratedAt":{"type":"string"},"metadata":{"type":"object","nullable":true,"properties":{"source":{"type":"string","enum":["system_fetch","manual_input"]},"title":{"type":"string"},"description":{"type":"string"},"ogImageUrl":{"type":"string"},"faviconUrl":{"type":"string"},"rawMetadata":{"type":"object","additionalProperties":{"nullable":true}},"fetchedAt":{"type":"string"},"providedAt":{"type":"string"},"providedBy":{"type":"string","format":"uuid"},"aiSummary":{"type":"string"},"aiSummaryGeneratedAt":{"type":"string"}},"required":["source"]}},"required":["id","workspaceId","createdBy","normalizedUrl","originalUrl","createdAt","updatedAt"]},"SearchBookmarksResponse":{"type":"object","properties":{"bookmarks":{"type":"array","items":{"$ref":"#/components/schemas/Bookmark"}},"totalCount":{"type":"number"}},"required":["bookmarks"]},"ListUserFeatureFlagsResponse":{"type":"object","properties":{"flags":{"type":"array","items":{"$ref":"#/components/schemas/UserFeatureFlag"}}},"required":["flags"]},"UserFeatureFlag":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"flagName":{"type":"string","example":"ai_summary_enabled"},"enabled":{"type":"boolean","example":true},"description":{"type":"string","example":"Flag to enable auto-generation of AI summaries"},"createdAt":{"type":"string","format":"date-time","example":"2024-12-19T10:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-12-19T10:00:00Z"}},"required":["userId","flagName","enabled","description","createdAt","updatedAt"]},"SetUserFeatureFlagRequest":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"description":{"type":"string","minLength":1,"example":"Flag to enable auto-generation of AI summaries"}},"required":["enabled","description"]}},"parameters":{}},"paths":{"/hc":{"get":{"summary":"Health check endpoint","description":"Returns the health status of the API","tags":["Health"],"responses":{"200":{"description":"Health check successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/bookmarks.create":{"post":{"summary":"Create bookmark","tags":["Bookmarks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookmarkRequest"}}}},"responses":{"200":{"description":"Bookmark created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookmarkResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Unauthorized access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}}}},"/api/v1/bookmarks.list":{"get":{"summary":"List bookmarks in workspace","tags":["Bookmarks"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000"},"required":true,"name":"workspaceId","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":20,"example":"20"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":0,"example":"0"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Bookmarks list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListBookmarksResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Unauthorized access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}}}},"/api/v1/bookmarks.search":{"get":{"summary":"Search bookmarks in workspace","tags":["Bookmarks"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000"},"required":true,"name":"workspaceId","in":"query"},{"schema":{"type":"string","minLength":1,"example":"typescript mcp"},"required":true,"name":"query","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":20,"example":"20"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":0,"example":"0"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Bookmarks search result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBookmarksResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Unauthorized access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}}}},"/admin/users/:userId/plan":{"put":{"summary":"Change user plan","description":"Change a user's plan type (Admin only)","tags":["Admin","Users"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"planType":{"type":"string","enum":["FREE","BASIC"],"example":"BASIC"}},"required":["planType"]}}}},"responses":{"200":{"description":"Plan updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/users/{userId}/feature-flags":{"get":{"summary":"Get feature flags for specific user","description":"Retrieve all feature flags for a specific user (Admin only)","tags":["Admin","Feature Flags"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"responses":{"200":{"description":"User feature flags retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListUserFeatureFlagsResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid admin credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/admin/users/{userId}/feature-flags/{flagName}":{"get":{"summary":"Get specific user feature flag","description":"Retrieve a specific feature flag for a user (Admin only)","tags":["Admin","Feature Flags"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"},{"schema":{"type":"string","example":"ai_summary_enabled","description":"Feature flag name"},"required":true,"description":"Feature flag name","name":"flagName","in":"path"}],"responses":{"200":{"description":"User feature flag retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFeatureFlag"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid admin credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Feature flag not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Set or update user feature flag","description":"Create or update a feature flag for a user (Admin only)","tags":["Admin","Feature Flags"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"},{"schema":{"type":"string","example":"ai_summary_enabled","description":"Feature flag name"},"required":true,"description":"Feature flag name","name":"flagName","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetUserFeatureFlagRequest"}}}},"responses":{"200":{"description":"Feature flag updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFeatureFlag"}}}},"201":{"description":"Feature flag created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFeatureFlag"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid admin credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete user feature flag","description":"Delete a specific feature flag for a user (Admin only)","tags":["Admin","Feature Flags"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"},{"schema":{"type":"string","example":"ai_summary_enabled","description":"Feature flag name"},"required":true,"description":"Feature flag name","name":"flagName","in":"path"}],"responses":{"204":{"description":"Feature flag deleted successfully"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid admin credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Feature flag not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}