{"openapi":"3.0.0","info":{"version":"1.0.0","title":"WebLinq API","description":"WebLinq API for web scraping, search, and content extraction"},"servers":[{"url":"https://api.weblinq.dev","description":"Production API Server"},{"url":"http://localhost:8787","description":"Local Development Server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your API token or session token"}},"schemas":{},"parameters":{}},"paths":{"/v1/user/verify-email":{"post":{"tags":["User"],"summary":"Verify if email exists","description":"Check if a user account exists for the given email address.","requestBody":{"description":"Email verification parameters","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Email verification result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"exists":{"type":"boolean"},"email":{"type":"string","format":"email"}},"required":["exists","email"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["email"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/verify-email-token":{"get":{"tags":["User"],"summary":"Verify email with token and redirect","description":"Custom email verification handler that processes the token and redirects to frontend dashboard with new_user parameter.","parameters":[{"schema":{"type":"string"},"required":false,"name":"token","in":"query"}],"responses":{"302":{"description":"Redirect to dashboard or sign-in","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/me":{"get":{"tags":["User"],"security":[{"bearerAuth":[]}],"summary":"Get current user information","description":"Returns the current user information. Works with both session-based authentication (browser) and API token-based authentication (server-to-server). Returns user details if authenticated, or guest info if not authenticated.","responses":{"200":{"description":"User information","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"user":{"nullable":true},"session":{"nullable":true},"apiToken":{"nullable":true},"authType":{"type":"string","enum":["session","api-token","none"]},"isAuthenticated":{"type":"boolean"},"message":{"type":"string"}},"required":["authType","isAuthenticated"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/credits":{"get":{"tags":["User"],"security":[{"bearerAuth":[]}],"summary":"Get user credit information","description":"Returns the current user credit balance, plan, and last refill date.","responses":{"200":{"description":"User credits information","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"balance":{"type":"number"},"plan":{"type":"string","enum":["free","pro"]},"lastRefill":{"type":"string","nullable":true}},"required":["balance","plan","lastRefill"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/clear-cache":{"get":{"tags":["User"],"security":[{"bearerAuth":[]}],"summary":"Clear all cached data for the user","description":"Deletes all cached entries for web operations (V1 and V2) for the authenticated user. This includes cached results from screenshot, markdown, PDF, scraping, and other web operation endpoints.","responses":{"200":{"description":"Cache cleared successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cleared":{"type":"boolean"},"message":{"type":"string"},"details":{"type":"object","properties":{"v1CacheCleared":{"type":"number"},"v2CacheCleared":{"type":"number"},"totalCleared":{"type":"number"},"method":{"type":"string","enum":["global-api","local-cache"]},"globalPurgeSuccess":{"type":"boolean"}},"required":["v1CacheCleared","v2CacheCleared","totalCleared","method","globalPurgeSuccess"]}},"required":["cleared","message","details"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/initialize":{"post":{"tags":["User"],"summary":"Initialize user resources","description":"Initialize WebDurableObject and other user resources for development environments.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1}},"required":["userId"]}}}},"responses":{"200":{"description":"User resources initialized successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"webDurableObjectInitialized":{"type":"boolean"},"message":{"type":"string"}},"required":["webDurableObjectInitialized","message"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/user/bootstrap-credits":{"post":{"tags":["User"],"security":[{"bearerAuth":[]}],"summary":"Bootstrap credits for existing users","description":"Assign initial credits to existing users who do not have credits yet.","responses":{"200":{"description":"Credits bootstrapped successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{}},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/api-keys/create":{"post":{"tags":["API Keys"],"security":[{"bearerAuth":[]}],"summary":"Create a new API key","description":"Create a new API key for the authenticated user. System defaults: wq_ prefix, 1000 requests per 24 hours rate limit, no expiration, free plan metadata.","requestBody":{"description":"API key creation parameters","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"start":{"type":"string","nullable":true,"description":"First few characters of the key for identification"},"prefix":{"type":"string","nullable":true},"userId":{"type":"string"},"enabled":{"type":"boolean"},"requestCount":{"type":"number"},"remaining":{"type":"number","nullable":true,"description":"Remaining uses (if limited)"},"lastRequest":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"key":{"type":"string","description":"Complete API key - shown only once during creation"}},"required":["id","name","start","prefix","userId","enabled","requestCount","remaining","lastRequest","expiresAt","createdAt","updatedAt","metadata","key"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["name"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/api-keys/list":{"get":{"tags":["API Keys"],"security":[{"bearerAuth":[]}],"summary":"List user API keys","description":"Get all API keys for the authenticated user","responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"start":{"type":"string","nullable":true,"description":"First few characters of the key for identification"},"prefix":{"type":"string","nullable":true},"userId":{"type":"string"},"enabled":{"type":"boolean"},"requestCount":{"type":"number"},"remaining":{"type":"number","nullable":true,"description":"Remaining uses (if limited)"},"lastRequest":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","start","prefix","userId","enabled","requestCount","remaining","lastRequest","expiresAt","createdAt","updatedAt","metadata"]}},"total":{"type":"number"}},"required":["apiKeys","total"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/api-keys/{id}":{"get":{"tags":["API Keys"],"security":[{"bearerAuth":[]}],"summary":"Get API key details","description":"Get details of a specific API key","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"API key details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"start":{"type":"string","nullable":true,"description":"First few characters of the key for identification"},"prefix":{"type":"string","nullable":true},"userId":{"type":"string"},"enabled":{"type":"boolean"},"requestCount":{"type":"number"},"remaining":{"type":"number","nullable":true,"description":"Remaining uses (if limited)"},"lastRequest":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","start","prefix","userId","enabled","requestCount","remaining","lastRequest","expiresAt","createdAt","updatedAt","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}},"delete":{"tags":["API Keys"],"security":[{"bearerAuth":[]}],"summary":"Delete API key","description":"Delete an existing API key. Note: API keys cannot be updated - create a new one if needed.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"API key deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/screenshot":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Capture screenshot of a web page","description":"Capture screenshot of the specified URL with optional configuration. Returns binary image data by default for optimal performance.","requestBody":{"description":"Screenshot parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0},"base64":{"type":"boolean","default":false,"description":"Return base64 string instead of binary Uint8Array"},"screenshotOptions":{"type":"object","properties":{"captureBeyondViewport":{"type":"boolean"},"clip":{"type":"object","properties":{"height":{"type":"integer","minimum":1},"width":{"type":"integer","minimum":1},"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"scale":{"type":"number","minimum":0.1,"maximum":10}},"required":["height","width","x","y"]},"encoding":{"type":"string","enum":["binary","base64"],"default":"binary"},"fromSurface":{"type":"boolean"},"fullPage":{"type":"boolean","default":true},"omitBackground":{"type":"boolean"},"optimizeForSpeed":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"type":{"type":"string","enum":["png","jpeg","webp"],"default":"png"}},"default":{}},"viewport":{"type":"object","properties":{"height":{"type":"integer","minimum":100,"maximum":2160,"default":800},"width":{"type":"integer","minimum":100,"maximum":3840,"default":1280},"deviceScaleFactor":{"type":"number","minimum":0.1,"maximum":10,"default":1},"hasTouch":{"type":"boolean","default":false},"isLandscape":{"type":"boolean","default":false},"isMobile":{"type":"boolean","default":false}}}},"required":["url"]}}}},"responses":{"200":{"description":"Screenshot captured successfully - returns binary image data by default","content":{"image/png":{"schema":{"type":"string","description":"Raw bytes; default response.","format":"binary"}},"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"metadata":{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"format":{"type":"string"},"size":{"type":"number"},"url":{"type":"string"},"timestamp":{"type":"string"}},"required":["width","height","format","size","url","timestamp"]},"permanentUrl":{"type":"string","format":"uri","description":"Permanent R2 storage URL for the image"},"fileId":{"type":"string","description":"Unique file ID for tracking"}},"required":["metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/markdown":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Extract markdown from a web page","description":"Convert web page content to markdown format","requestBody":{"description":"Markdown extraction parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0}},"required":["url"]}}}},"responses":{"200":{"description":"Markdown extracted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"markdown":{"type":"string"},"metadata":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"timestamp":{"type":"string"},"wordCount":{"type":"number"}},"required":["url","timestamp","wordCount"]}},"required":["markdown","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/ai-extract":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"AI extract structured data from a web page","description":"AI extract JSON data or text content using AI-powered parsing","requestBody":{"description":"AI extract parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0},"responseType":{"type":"string","enum":["json","text"],"default":"json"},"prompt":{"type":"string","minLength":1,"maxLength":1000},"response_format":{"type":"object","properties":{"type":{"type":"string","enum":["json_schema"]},"json_schema":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","json_schema"]},"instructions":{"type":"string","maxLength":500}},"required":["url"]}}}},"responses":{"200":{"description":"AI extract completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"extracted":{"type":"object","additionalProperties":{"nullable":true}},"text":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"timestamp":{"type":"string"},"model":{"type":"string"},"responseType":{"type":"string","enum":["json","text"]},"extractionType":{"type":"string","enum":["prompt","schema"]},"fieldsExtracted":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"}},"required":["url","timestamp","model","responseType","extractionType"]}},"required":["metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/content":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Get raw HTML content from a web page","description":"Retrieve the raw HTML content of the specified URL","requestBody":{"description":"Content extraction parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0}},"required":["url"]}}}},"responses":{"200":{"description":"HTML content retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"content":{"type":"string"},"metadata":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"timestamp":{"type":"string"},"contentType":{"type":"string"}},"required":["url","timestamp","contentType"]}},"required":["content","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/scrape":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Scrape specific elements from a web page","description":"Extract specific HTML elements using CSS selectors","requestBody":{"description":"Element scraping parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"elements":{"type":"array","items":{"type":"object","properties":{"selector":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}},"required":["selector"]}},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}}},"required":["url","elements"]}}}},"responses":{"200":{"description":"Elements scraped successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"elements":{"type":"array","items":{"type":"object","properties":{"selector":{"type":"string"},"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["selector","data"]}},"metadata":{"type":"object","properties":{"url":{"type":"string"},"timestamp":{"type":"string"},"elementsFound":{"type":"number"}},"required":["url","timestamp","elementsFound"]}},"required":["elements","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"},{"code":"invalid_type","expected":"array","received":"undefined","path":["elements"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/links":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Extract links from a web page","description":"Get all links from the specified URL with optional filtering","requestBody":{"description":"Link extraction parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"includeExternal":{"type":"boolean","default":true},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0}},"required":["url"]}}}},"responses":{"200":{"description":"Links extracted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","enum":["internal","external"]}},"required":["url","text","type"]}},"metadata":{"type":"object","properties":{"url":{"type":"string"},"timestamp":{"type":"string"},"totalLinks":{"type":"number"},"internalLinks":{"type":"number"},"externalLinks":{"type":"number"}},"required":["url","timestamp","totalLinks","internalLinks","externalLinks"]}},"required":["links","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/search":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Search the web","description":"Perform a web search and return results","requestBody":{"description":"Search parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"limit":{"type":"number","minimum":1,"maximum":10,"default":5}},"required":["query"]}}}},"responses":{"200":{"description":"Search completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"snippet":{"type":"string"},"source":{"type":"string","enum":["duckduckgo","startpage","yandex","bing"]}},"required":["title","url","snippet","source"]}},"metadata":{"type":"object","properties":{"query":{"type":"string"},"totalResults":{"type":"number"},"searchTime":{"type":"number"},"sources":{"type":"array","items":{"type":"string"}},"timestamp":{"type":"string"}},"required":["query","totalResults","searchTime","sources","timestamp"]}},"required":["results","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["query"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/web/pdf":{"post":{"tags":["Web"],"security":[{"bearerAuth":[]}],"summary":"Generate PDF from a web page","description":"Convert a web page to PDF format. Returns binary PDF data by default for optimal performance.","requestBody":{"description":"PDF generation parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"waitTime":{"type":"integer","minimum":0,"maximum":5000,"default":0},"base64":{"type":"boolean","default":false,"description":"Return base64 string instead of binary Uint8Array"}},"required":["url"]}}}},"responses":{"200":{"description":"PDF generated successfully - returns binary PDF data by default","content":{"application/pdf":{"schema":{"type":"string","description":"Raw bytes; default response.","format":"binary"}},"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"metadata":{"type":"object","properties":{"size":{"type":"number"},"url":{"type":"string"},"timestamp":{"type":"string"}},"required":["size","url","timestamp"]},"permanentUrl":{"type":"string","description":"Permanent R2 storage URL for the PDF"},"fileId":{"type":"string","description":"Unique file ID for tracking"}},"required":["metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["url"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/files/list":{"get":{"tags":["Files"],"security":[{"bearerAuth":[]}],"summary":"List user files","description":"List all files (screenshots, PDFs) associated with the authenticated user","parameters":[{"schema":{"type":"string","enum":["screenshot","pdf"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["created_at","filename"],"default":"created_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"}],"responses":{"200":{"description":"Files listed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"sqliteStatus":{"type":"object","properties":{"enabled":{"type":"boolean"},"available":{"type":"boolean"},"userId":{"type":"string"}},"required":["enabled","available","userId"]},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["screenshot","pdf"]},"url":{"type":"string"},"filename":{"type":"string"},"r2_key":{"type":"string"},"public_url":{"type":"string"},"metadata":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"}},"required":["id","type","url","filename","r2_key","public_url","metadata","created_at"]}},"totalFiles":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["sqliteStatus","files","totalFiles","hasMore"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"]}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/files/delete":{"post":{"tags":["Files"],"security":[{"bearerAuth":[]}],"summary":"Delete a file","description":"Delete a file from database and optionally from R2 storage","requestBody":{"description":"File deletion parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","minLength":1},"deleteFromR2":{"type":"boolean","default":false,"description":"Also delete the file from R2 storage"}},"required":["fileId"]}}}},"responses":{"200":{"description":"File deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"fileId":{"type":"string"},"wasFound":{"type":"boolean"},"deletedFromDatabase":{"type":"boolean"},"deletedFromR2":{"type":"boolean"},"deletedFile":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["screenshot","pdf"]},"url":{"type":"string"},"filename":{"type":"string"},"r2_key":{"type":"string"},"public_url":{"type":"string"},"metadata":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"}},"required":["id","type","url","filename","r2_key","public_url","metadata","created_at"]},"error":{"type":"string"}},"required":["fileId","wasFound","deletedFromDatabase","deletedFromR2"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["fileId"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v1/system/update-user-plan":{"post":{"tags":["System"],"security":[{"bearerAuth":[]}],"summary":"Update user plan","description":"Update a user's subscription plan (free/pro) - Admin only","requestBody":{"description":"User plan update parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1},"plan":{"type":"string","enum":["free","pro"]}},"required":["userId","plan"]}}}},"responses":{"200":{"description":"User plan updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"userId":{"type":"string"},"plan":{"type":"string","enum":["free","pro"]},"updatedBy":{"type":"string"},"updatedAt":{"type":"string"}},"required":["userId","plan","updatedBy","updatedAt"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["userId"],"message":"Required"},{"expected":"'free' | 'pro'","received":"undefined","code":"invalid_type","path":["plan"],"message":"Plan is required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v2/web/search":{"post":{"tags":["Web v2"],"security":[{"bearerAuth":[]}],"summary":"Search the web (v2)","description":"Perform a web search and return results using the v2 API","requestBody":{"description":"Search parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"limit":{"type":"number","minimum":1,"maximum":20,"default":10}},"required":["query"]}}}},"responses":{"200":{"description":"Search completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"snippet":{"type":"string"},"favicon":{"type":"string"},"publishedDate":{"type":"string"}},"required":["id","title","url","snippet"]}},"metadata":{"type":"object","properties":{"query":{"type":"string"},"totalResults":{"type":"number"},"searchTime":{"type":"number"},"timestamp":{"type":"string"},"requestId":{"type":"string"}},"required":["query","totalResults","searchTime","timestamp"]}},"required":["results","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["query"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}},"/v2/web/yt-captions":{"post":{"tags":["Web v2"],"security":[{"bearerAuth":[]}],"summary":"Extract YouTube captions","description":"Extract captions/subtitles from a YouTube video using video ID","requestBody":{"description":"YouTube caption extraction parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"type":"string","minLength":1,"maxLength":100,"description":"YouTube video ID"},"lang":{"type":"string","minLength":2,"maxLength":5,"default":"en","description":"Language code for subtitles (e.g., \"en\", \"fr\", \"de\")"},"includeVideoDetails":{"type":"boolean","default":false,"description":"Whether to include video details along with captions"}},"required":["videoId"]}}}},"responses":{"200":{"description":"Captions extracted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"videoId":{"type":"string"},"language":{"type":"string"},"captions":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"dur":{"type":"string"},"text":{"type":"string"}},"required":["start","dur","text"]}},"videoDetails":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}},"required":["title","description"]},"metadata":{"type":"object","properties":{"totalCaptions":{"type":"number"},"extractionTime":{"type":"number"},"timestamp":{"type":"string"}},"required":["totalCaptions","extractionTime","timestamp"]}},"required":["videoId","language","captions","metadata"]},"creditsCost":{"type":"number","description":"Credits consumed by this operation"},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracing"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when the response was generated"}},"required":["success","data","requestId","timestamp"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["videoId"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}},"required":["message","code"]}},"required":["success","error"],"example":{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED","requestId":"bf68e5de-f6ef-479f-9328-6d3f48d5b7d4"}}}}}}}}}}}