{"openapi":"3.0.0","info":{"title":"Breachspot API","version":"1.0.0","description":"This is a REST API application for credential search and breach data analysis. It provides comprehensive search capabilities across multiple data sources including Credshed, Twitter, and various breach incident collections. Underground Intelligence covers non-indexed or restricted sources (forums/markets, IM channels, leak sites, pastebins, stealer dumps) for early detection of breach claims, access sales, and adversary chatter. It powers Breachspot’s identity exposure alerts and IOC enrichment. The API supports dual authentication systems for different client types and includes advanced filtering, pagination, and credit-based access control.","contact":{"name":"Edgewatch Breachspot API Support","url":"https://support.edgewatch.com/","email":"support@edgewatch.com","support":{"website":"https://support.edgewatch.com/","kb":"https://edgewatch.com/kb/breachspot-api"}},"license":{"name":"Edgewatch Breachspot KB - Website","url":"https://edgewatch.com/kb/breachspot-api"},"termsOfService":"https://edgewatch.com/legal/terms-of-use/"},"tags":[{"name":"Auth","description":"Authentication endpoints"},{"name":"Search","description":"Search endpoints"},{"name":"Monitors","description":"Monitor endpoints"},{"name":"Underground","description":"Underground source monitoring."},{"name":"Actors","parent":"Underground","description":"Threat actors including gangs, brokers, and communication channels"},{"name":"Sources","description":"Intelligence sources and mirrors including onion sites, clearnet, IM platforms, and forums"},{"name":"Posts","description":"Underground posts including listings, leak notes, market ads, and breach claims"},{"name":"Wallets","description":"Cryptocurrency wallet tracking and attribution"},{"name":"Law Enforcement","description":"Restricted endpoints for law enforcement access. Provides technical artifacts and dump information for lawful investigations. All access is logged for audit purposes."}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","name":"x-client-id","in":"header"},"ClientSecret":{"type":"apiKey","name":"x-client-secret","in":"header"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"RefreshToken":{"type":"http","name":"x-refresh-token","in":"header"},"FrontendToken":{"type":"apiKey","name":"x-frontend-token","in":"header","description":"Frontend authentication token for UI applications"},"ClientType":{"type":"apiKey","name":"x-client-type","in":"header","description":"Client type identifier (ui for frontend, api for external clients)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"Post":{"type":"object","properties":{"post_id":{"type":"string","description":"Generated unique post ID (MD5 hash of group_name-post_title)"},"_id":{"type":"string","description":"Post ID"},"group_name":{"type":"string","description":"Name of the threat actor group"},"post_title":{"type":"string","description":"Title of the post"},"post_url":{"type":"string","description":"URL to the original post"},"discovered":{"type":"string","format":"date-time","description":"When the post was discovered"},"published":{"type":"string","format":"date-time","description":"When the post was published"},"victim":{"type":"object","description":"Target information if available (database field name preserved)"},"screenshots":{"type":"array","items":{"type":"string"},"description":"Screenshot URLs"}}},"Group":{"type":"object","properties":{"_id":{"type":"string","description":"Group ID"},"name":{"type":"string","description":"Group name"},"slug":{"type":"string","description":"URL-friendly group identifier"},"description":{"type":"string","description":"Group description"},"active":{"type":"boolean","description":"Whether the group is currently active"},"first_seen":{"type":"string","format":"date-time","description":"First observed activity"},"last_seen":{"type":"string","format":"date-time","description":"Most recent activity"},"locations":{"type":"array","items":{"type":"object"},"description":"Known locations/sites"}}},"Market":{"type":"object","properties":{"_id":{"type":"string","description":"Market ID"},"name":{"type":"string","description":"Market name"},"description":{"type":"string","description":"Market description"}}},"Leak":{"type":"object","properties":{"_id":{"type":"string","description":"Leak ID"},"title":{"type":"string","description":"Leak title"},"source":{"type":"string","description":"Source of the leak"},"date":{"type":"string","format":"date-time","description":"Date of the leak"}}},"CredentialItem":{"type":"object","properties":{"url":{"type":"string","description":"Associated URL or domain"},"email":{"type":"string","description":"Email address associated with the credential"},"name":{"type":"string","description":"Optional name associated with the credential"},"username":{"type":"string","description":"Username associated with the credential"},"password_sha1":{"type":"string","description":"SHA-1 hash of the password (API never returns plain password)"},"password_ntlm":{"type":"string","description":"NTLM hash of the password (when available)"},"password_strength":{"type":"number","description":"Password strength score"},"unlocked":{"type":"boolean","description":"Whether the credential is unlocked/accessible"},"is_email":{"type":"boolean","description":"Whether the credential represents an email address"},"created_at":{"type":"string","description":"Timestamp when the credential was created"},"source":{"type":"string","description":"Friendly display name of the data source (e.g. \"Anti Public Combo List\", \"Twitter database leak\")"}}},"SearchResult":{"type":"object","properties":{"query":{"type":"object","properties":{"type":{"type":"string","enum":["email","domain","username"],"description":"Type of search performed"},"value":{"type":"string","description":"Search term value"}}},"count":{"type":"integer","description":"Total number of matching records across all data sources, regardless of the `limit` query parameter. May be capped for very large result sets (see `count_capped`)."},"count_capped":{"type":"boolean","description":"Present and true when at least one data source hit the internal occurrence cap or count timeout, meaning `count` is a lower bound rather than an exact total."},"matches":{"type":"array","items":{"type":"object","properties":{"count":{"type":"number","description":"Number of occurrences found"},"source":{"type":"object","properties":{"name":{"type":"string","description":"Collection name"},"description":{"type":"string","description":"Collection description"},"breached_data":{"type":"array","items":{"type":"string"},"description":"Types of data that were breached"},"total_records":{"type":"number","description":"Total number of records in the collection"},"date":{"type":"string","format":"date","description":"Date of the breach/incident"}}}}}}}},"CollectionStats":{"type":"object","properties":{"name":{"type":"string","description":"Friendly display name of the collection"},"slug":{"type":"string","description":"URL-friendly identifier (name lowercased, spaces as underscores)"},"description":{"type":"string","description":"Collection description"},"total_records":{"type":"number","description":"Total number of records in the collection"},"date":{"type":"string","format":"date","description":"Date of the breach/incident"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with the collection"}}},"AdvancedSearchFilters":{"type":"object","properties":{"since":{"type":"string","format":"date","description":"Start date (inclusive) for filtering records (YYYY-MM-DD)"},"until":{"type":"string","format":"date","description":"End date (inclusive) for filtering records (YYYY-MM-DD)"},"domain":{"type":"string","description":"Domain to filter records by"},"email":{"type":"string","description":"Email address to filter records by"},"username":{"type":"string","description":"Username to filter records by"},"include_fields":{"type":"array","items":{"type":"string"},"description":"List of fields to include in the result"},"where":{"type":"array","description":"Advanced filter conditions","items":{"type":"object","properties":{"field":{"type":"string","description":"Field name to filter on"},"operator":{"type":"string","enum":["exists","cidr","like","eq","ne","gt","lt","gte","lte","in","nin"],"description":"Comparison operator"},"value":{"type":"string","description":"Value for the filter (if required by operator)"}}}}}},"AdvancedSearchRequest":{"type":"object","required":["filters"],"properties":{"filters":{"$ref":"#/components/schemas/AdvancedSearchFilters"},"limit":{"type":"integer","description":"Maximum number of results to return (default 100, max 1000)","default":100,"minimum":1,"maximum":1000},"page":{"type":"integer","description":"Page number (default 1)","default":1,"minimum":1},"include_plain_credentials":{"type":"boolean","deprecated":true,"description":"Ignored. API always returns masked emails and hashed passwords (SHA-1, NTLM) only.","default":false}}},"AdvancedSearchResponse":{"type":"object","required":["items","total","total_unlocked","page","page_size"],"properties":{"items":{"type":"array","description":"Array of credential records","items":{"oneOf":[{"$ref":"#/components/schemas/CredentialItem"}]}},"total":{"type":"integer","description":"Total number of matching records"},"total_unlocked":{"type":"integer","description":"Total number of unlocked records"},"page":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"},"total_partial":{"type":"integer","description":"When include_fields is used, number of records that matched the query but did not have all requested fields (only present when include_fields was applied)"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"message":{"type":"string","description":"Error message"},"error":{"type":"string","description":"Error details (for unauthorized responses)"}}},"PaginationMetadata":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"},"total_pages":{"type":"integer","description":"Total number of pages"},"has_next":{"type":"boolean","description":"Whether there are more pages"},"has_previous":{"type":"boolean","description":"Whether there are previous pages"}}},"SearchMetadata":{"type":"object","properties":{"query_time_ms":{"type":"number","description":"Query execution time in milliseconds"},"total_results":{"type":"number","description":"Total number of matching results"},"data_sources":{"type":"array","items":{"type":"string"},"description":"Data sources that were queried"},"filters_applied":{"type":"object","description":"Summary of filters that were applied to the search"}}},"DownloadToken":{"type":"object","properties":{"token":{"type":"string","description":"Unique download token"},"expires_at":{"type":"string","format":"date-time","description":"Token expiration timestamp"},"max_downloads":{"type":"integer","description":"Maximum number of downloads allowed"},"download_count":{"type":"integer","description":"Current number of downloads used"}}},"SearchTerm":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["email","phone","business_name","name","username","ip","domain"],"description":"Type of search term"},"value":{"type":"string","description":"The search term value"},"is_regex":{"type":"boolean","description":"Whether the search term is a regex pattern","default":false}}},"BreachEvent":{"type":"object","required":["uuid","breach_event_type","created_at"],"properties":{"uuid":{"type":"string","description":"Unique identifier for the breach event"},"breach_event_type":{"type":"string","enum":["watch_list_created","watch_list_updated","watch_list_deleted","breach_collection_published"],"description":"Type of breach event"},"created_at":{"type":"string","format":"date-time","description":"When the event occurred"}}},"WatchList":{"type":"object","required":["uuid","client_guid"],"properties":{"uuid":{"type":"string","description":"Unique identifier for the watch list"},"client_guid":{"type":"string","description":"Client identifier associated with the watch list"},"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/SearchTerm"},"description":"Array of search terms to monitor"},"results":{"type":"array","description":"Array of search results"},"events":{"type":"array","items":{"$ref":"#/components/schemas/BreachEvent"},"description":"Array of breach events"},"is_active":{"type":"boolean","description":"Whether the watch list is currently active","default":true},"is_deleted":{"type":"boolean","description":"Whether the watch list is deleted","default":false},"created_at":{"type":"string","format":"date-time","description":"When the watch list was created"},"updated_at":{"type":"string","format":"date-time","description":"When the watch list was last updated"}}},"CreateWatchListRequest":{"type":"object","required":["client_guid"],"properties":{"client_guid":{"type":"string","description":"Client identifier for the watch list"},"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/SearchTerm"},"description":"Initial search terms to monitor"},"is_active":{"type":"boolean","description":"Whether the watch list should be active initially","default":true}}},"UpdateWatchListRequest":{"type":"object","properties":{"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/SearchTerm"},"description":"Updated search terms"},"is_active":{"type":"boolean","description":"Whether the watch list should be active"}}},"WatchListStats":{"type":"object","properties":{"total_watch_lists":{"type":"integer","description":"Total number of watch lists"},"active_watch_lists":{"type":"integer","description":"Number of active watch lists"},"inactive_watch_lists":{"type":"integer","description":"Number of inactive watch lists"}}}},"responses":{"RateLimitExceeded":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","example":429},"message":{"type":"string","example":"Rate limit exceeded. Please try again later."},"retry_after":{"type":"number","description":"Seconds to wait before retrying","example":60}}}}}},"InsufficientCredits":{"description":"Insufficient credits in wallet","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","example":402},"message":{"type":"string","example":"Insufficient credits. Please recharge your wallet."},"required_credits":{"type":"number","description":"Credits required for this operation","example":10},"available_credits":{"type":"number","description":"Credits currently available","example":5}}}}}}}},"security":[{"BearerAuth":[]}],"paths":{"/auth/token":{"get":{"tags":["Auth"],"x-production":true,"summary":"Obtain an access token and a refresh token","description":"Obtains an access token and a refresh token","security":[{"ClientId":[]},{"ClientSecret":[]}],"responses":{"200":{"description":"Access and refresh tokens","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The access token (JWT)"},"refreshToken":{"type":"string","description":"The refresh token (JWT)"}}}}}},"500":{"description":"Error obtaining token"}}}},"/auth/validate":{"get":{"x-production":true,"tags":["Testing"],"security":[{"BearerAuth":[]}],"summary":"Validate a recently generated token","description":"Validates a recently generated token and returns the basic data of the api-client and its owner.","responses":{"200":{"description":"Basic data of the api-client owner","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string","description":"The unique identifier of the api-client"},"name":{"type":"string","description":"The name of the api-client"},"client":{"type":"string","description":"The client GUID"},"targetApis":{"type":"array","description":"The target APIs for the client","items":{"type":"string","description":"The target API name"}},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the client"},"expiresAt":{"type":"string","format":"date-time","description":"The expiration date of the client"}}}}}},"401":{"description":"Unauthorized"},"500":{"description":"Error obtaining data"}}}},"/auth/refresh":{"get":{"x-production":true,"tags":["Auth"],"summary":"Refresh an access token","description":"Refresh an expired access token using a valid refresh token (stateless JWT)","security":[{"RefreshToken":[]}],"responses":{"200":{"description":"Refreshed access and refresh tokens","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The new access token (JWT)"},"refreshToken":{"type":"string","description":"The new refresh token (JWT)"}}}}}},"400":{"description":"Missing or invalid refresh token"},"403":{"description":"Invalid or expired refresh token"},"500":{"description":"Error obtaining data"}}}},"/le/artifacts/{post_id}":{"get":{"summary":"Get post artifacts for law enforcement","description":"Returns technical metadata including hashes, torrent info, and deep headers without PII content. Access is logged for audit purposes.","tags":["Law Enforcement"],"x-production":true,"parameters":[{"in":"path","name":"post_id","required":true,"schema":{"type":"string"},"description":"Post ID"}],"responses":{"200":{"description":"Post artifacts and technical metadata","content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string"},"group":{"$ref":"#/components/schemas/Group","description":"Full group information including name, locations, and metadata"},"discovered":{"type":"string","format":"date-time"},"published":{"type":"string","format":"date-time"},"metadata":{"type":"object","properties":{"hashes":{"type":"array","items":{"type":"string"}},"torrents":{"type":"array","items":{"type":"object"}},"headers":{"type":"object"},"file_count":{"type":"integer"},"total_size":{"type":"integer"},"url_patterns":{"type":"array","items":{"type":"string"}},"screenshot_ids":{"type":"array","items":{"type":"string"}}}},"indicators":{"type":"object","properties":{"has_screenshots":{"type":"boolean"},"has_files":{"type":"boolean"},"source_type":{"type":"string"}}}}}}}},"403":{"description":"Access denied - law enforcement credentials required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal server error"}},"security":[{"BearerAuth":[]}]}},"/le/dumps/{post_id}":{"get":{"summary":"Get raw dump information for lawful investigations","description":"Returns information about raw data dumps if mirroring is enabled. Not available on public instances by default. All access is logged with NDA acknowledgment for audit purposes. References ransomlook.io for public data access.","tags":["Law Enforcement"],"x-production":true,"parameters":[{"in":"path","name":"post_id","required":true,"schema":{"type":"string"},"description":"Post ID"}],"responses":{"200":{"description":"Dump availability information","content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string"},"group":{"$ref":"#/components/schemas/Group","description":"Full group information including name, locations, and metadata"},"title":{"type":"string"},"discovered":{"type":"string","format":"date-time"},"published":{"type":"string","format":"date-time"},"dump_availability":{"type":"object","properties":{"available":{"type":"boolean"},"mirror_url":{"type":"string","nullable":true},"mirror_status":{"type":"string"},"last_verified":{"type":"string","format":"date-time","nullable":true}}},"access_notes":{"type":"string"},"legal_notice":{"type":"string"}}}}}},"403":{"description":"Access denied - law enforcement credentials required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal server error"},"503":{"description":"Service not available - raw dump mirroring not enabled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"post_id":{"type":"string"},"reference":{"type":"string"}}}}}}},"security":[{"BearerAuth":[]}]}},"/underground/recent":{"get":{"summary":"Get recent posts","tags":["Posts"],"x-production":true,"parameters":[{"in":"query","name":"number","schema":{"type":"integer","default":100},"description":"Number of recent posts to return"}],"responses":{"200":{"description":"List of recent posts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/feed":{"get":{"summary":"Get latest posts with their attributed target (feed)","tags":["Posts"],"x-production":true,"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Number of feed items. Unauthenticated 1-10; authenticated 1-500."},{"in":"query","name":"offset","schema":{"type":"integer","default":0},"description":"Number of feed items to skip (authenticated only). Use for load-more pagination."},{"in":"query","name":"detailed","schema":{"type":"boolean","default":false},"description":"If true (and authenticated), return full post+target/entity for incident details view."},{"in":"query","name":"date_from","schema":{"type":"string","format":"date"},"description":"Filter posts from this date (YYYY-MM-DD). Authenticated only."},{"in":"query","name":"date_to","schema":{"type":"string","format":"date"},"description":"Filter posts until this date (YYYY-MM-DD). Authenticated only."},{"in":"query","name":"period","schema":{"type":"string","enum":["day","week","month","year"]},"description":"Time window when date_from/date_to not set (e.g. week = last 7 days). Authenticated only."},{"in":"query","name":"country","schema":{"type":"string"},"description":"Filter by country code. Authenticated only."},{"in":"query","name":"city","schema":{"type":"string"},"description":"Filter by city (entity-level). Authenticated only."},{"in":"query","name":"company","schema":{"type":"string"},"description":"Filter by company/target name (entity-level). Authenticated only."},{"in":"query","name":"industry","schema":{"type":"string"},"description":"Filter by industry/sector. Authenticated only."},{"in":"query","name":"type","schema":{"type":"string"},"description":"Filter by incident type (e.g. extortion). Authenticated only."},{"in":"query","name":"group","schema":{"type":"string"},"description":"Filter by group slug. Authenticated only."}],"responses":{"200":{"description":"List of feed items (date, target, group_name, industry, country, region, description) or detailed incident objects when detailed=true.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"target":{"type":"string"},"group_name":{"type":"string"},"industry":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"description":{"type":"string"}}}}}}},"403":{"description":"detailed=true requires authentication"},"500":{"description":"Internal server error"}}}},"/underground/last":{"get":{"summary":"Get posts from last X days","tags":["Posts"],"x-production":true,"parameters":[{"in":"path","name":"number","schema":{"type":"integer","default":1},"description":"Number of days to look back"}],"responses":{"200":{"description":"List of posts from the last X days","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/markets":{"get":{"summary":"Get list of markets","tags":["Actors"],"x-production":true,"responses":{"200":{"description":"List of market names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/group/{name}":{"get":{"summary":"Get group info and posts","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"},"description":"Name of the group"}],"responses":{"200":{"description":"Group information and posts","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Group"},{"type":"array","items":{"$ref":"#/components/schemas/Post"}}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/market/{name}":{"get":{"summary":"Get market info and posts","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"},"description":"Name of the market"}],"responses":{"200":{"description":"Market information and posts","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Market"},{"type":"array","items":{"$ref":"#/components/schemas/Post"}}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/post/{name}/{postname}":{"get":{"summary":"Get specific post details","tags":["Posts"],"x-production":true,"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"},"description":"Name of the group/market"},{"in":"path","name":"postname","required":true,"schema":{"type":"string"},"description":"Name of the post"}],"responses":{"200":{"description":"Post details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/posts/{id}":{"get":{"summary":"Get post by ID","tags":["Posts"],"x-production":true,"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Post ID"}],"responses":{"200":{"description":"Post details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"404":{"description":"Post not found"},"500":{"description":"Internal server error"}}}},"/underground/posts/{year}/{month}":{"get":{"summary":"Get posts by year and month","tags":["Posts"],"x-production":true,"parameters":[{"in":"path","name":"year","required":true,"schema":{"type":"integer"},"description":"Year to filter posts"},{"in":"path","name":"month","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Month to filter posts (optional)"}],"responses":{"200":{"description":"List of posts for the specified year/month","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/screenshots":{"get":{"summary":"Get screenshots for all posts","tags":["Sources"],"x-production":true,"responses":{"200":{"description":"List of screenshots","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/posts/period/{start_date}/{end_date}":{"get":{"summary":"Get posts within a date period","tags":["Posts"],"x-production":true,"parameters":[{"in":"path","name":"start_date","required":true,"schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD format)"},{"in":"path","name":"end_date","required":true,"schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD format)"}],"responses":{"200":{"description":"List of posts within the specified period","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/underground/groups":{"get":{"summary":"List groups with filters","tags":["Actors"],"x-production":true,"parameters":[{"in":"query","name":"search","schema":{"type":"string"},"description":"Search query for group name or metadata"},{"in":"query","name":"active","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"has_sites","schema":{"type":"boolean"},"description":"Filter by presence of sites/locations"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of groups","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Group"}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/groups/{slug}":{"get":{"summary":"Get group profile by slug","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"},"description":"Group slug/name"}],"responses":{"200":{"description":"Group details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"404":{"description":"Group not found"},"500":{"description":"Internal server error"}}}},"/underground/groups/{slug}/sites":{"get":{"summary":"Get sites/locations for a group","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"},"description":"Group slug/name"},{"in":"query","name":"type","schema":{"type":"string","enum":["dls","fs","chat","admin"]},"description":"Filter by site type"}],"responses":{"200":{"description":"List of sites","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group_slug":{"type":"string"},"type":{"type":"string","enum":["dls","fs","chat","admin"]},"url":{"type":"string"},"status":{"type":"string","enum":["online","offline","unknown"]},"last_check":{"type":"string","format":"date-time"},"screenshot_id":{"type":"string"}}}}}}}}},"500":{"description":"Internal server error"}}}},"/underground/groups/{slug}/posts":{"get":{"summary":"Get posts for a group with pagination","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"},"description":"Group slug/name"},{"in":"query","name":"since","schema":{"type":"string","format":"date"},"description":"Filter posts since this date"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of posts","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/sites":{"get":{"summary":"List all sites across groups","tags":["Sources"],"x-production":true,"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["dls","fs","chat","admin"]},"description":"Filter by site type"},{"in":"query","name":"group","schema":{"type":"string"},"description":"Filter by group slug"},{"in":"query","name":"online","schema":{"type":"boolean"},"description":"Filter by online status"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of sites","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/screenshots/{id}":{"get":{"summary":"Get screenshot by ID","tags":["Sources"],"x-production":true,"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Screenshot ID"}],"responses":{"200":{"description":"Screenshot details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"post_title":{"type":"string"},"group_name":{"type":"string"}}}}}},"404":{"description":"Screenshot not found"},"500":{"description":"Internal server error"}}}},"/underground/posts":{"get":{"summary":"Search and list posts with comprehensive filters","tags":["Posts"],"x-production":true,"parameters":[{"in":"query","name":"group","schema":{"type":"string"},"description":"Filter by group slug"},{"in":"query","name":"q","schema":{"type":"string"},"description":"Search query"},{"in":"query","name":"country","schema":{"type":"string"},"description":"Filter by country code"},{"in":"query","name":"sector","schema":{"type":"string"},"description":"Filter by sector"},{"in":"query","name":"source_type","schema":{"type":"string"},"description":"Filter by source type"},{"in":"query","name":"since","schema":{"type":"string","format":"date"},"description":"Filter posts since this date"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of posts","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/targets":{"get":{"summary":"List targets extracted from posts","tags":["Targets"],"x-production":true,"parameters":[{"in":"query","name":"group","schema":{"type":"string"},"description":"Filter by group slug"},{"in":"query","name":"domain","schema":{"type":"string"},"description":"Filter by domain"},{"in":"query","name":"country","schema":{"type":"string"},"description":"Filter by country code"},{"in":"query","name":"sector","schema":{"type":"string"},"description":"Filter by sector"},{"in":"query","name":"since","schema":{"type":"string","format":"date"},"description":"Filter targets since this date"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of targets","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"sector":{"type":"string"},"first_seen":{"type":"string"},"last_seen":{"type":"string"},"posts":{"type":"array","items":{"type":"object"}}}}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/targets/{id}":{"get":{"summary":"Get target by ID","tags":["Targets"],"x-production":true,"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Target ID"}],"responses":{"200":{"description":"Target details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"sector":{"type":"string"},"first_seen":{"type":"string"},"last_seen":{"type":"string"},"posts":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Target not found"},"500":{"description":"Internal server error"}}}},"/underground/sources/telegram":{"get":{"summary":"Get Telegram messages as sources","tags":["Sources"],"x-production":true,"parameters":[{"in":"query","name":"channel","schema":{"type":"string"},"description":"Filter by channel name"},{"in":"query","name":"since","schema":{"type":"string","format":"date"},"description":"Filter messages since this date"},{"in":"query","name":"limit","schema":{"type":"integer","default":100},"description":"Maximum number of results"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Pagination cursor"}],"responses":{"200":{"description":"List of Telegram messages","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"group_name":{"type":"string"},"message":{"type":"string"},"date":{"type":"string"}}}},"next_cursor":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server error"}}}},"/underground/graph/target/{target_id}":{"get":{"summary":"Get target-centric relationship graph","tags":["Targets"],"x-production":true,"parameters":[{"in":"path","name":"target_id","required":true,"schema":{"type":"string"},"description":"Target ID"}],"responses":{"200":{"description":"Graph data","content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object"}}}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"type":{"type":"string"}}}}}}}}},"500":{"description":"Internal server error"}}}},"/underground/graph/group/{slug}":{"get":{"summary":"Get group-centric relationship graph","tags":["Actors"],"x-production":true,"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"},"description":"Group slug"}],"responses":{"200":{"description":"Graph data","content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object"}}}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"type":{"type":"string"}}}}}}}}},"500":{"description":"Internal server error"}}}},"/stats":{"get":{"summary":"Get Database Statistics","tags":["Statistics"],"description":"Retrieves comprehensive statistics and metadata from all database collections including total record counts, collection descriptions, and breach information.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved database statistics","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CollectionStats"}},"example":[{"name":"Anti Public Combo List","slug":"anti_public_combo_list","description":"A massive compilation of over 457 million unique email and password pairs.","total_records":3300000000,"date":"2016-12-01","tags":["breach","credential stuffing","password reuse"],"breached_data":["email","password"]},{"name":"Twitter database leak","slug":"twitter_database_leak","description":"Around 210m customer records were exposed in a data breach.","total_records":210000000,"date":"2021-01-01","tags":[],"breached_data":["Email Address","Name","Username","Follower Amount","Created At"]}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error while retrieving statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/breaches/search/advanced":{"post":{"summary":"Advanced Search for Credentials","tags":["Search"],"description":"Advanced search endpoint with comprehensive filtering and pagination capabilities. Supports complex queries across multiple data sources with flexible filtering options.","x-production":true,"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedSearchRequest"},"example":{"filters":{"since":"2024-01-01","until":"2025-08-01","email":"user@example.com","include_fields":["email","username","ip","password_hash"],"where":[{"field":"password_hash","operator":"exists"},{"field":"ip","operator":"cidr","value":"203.0.113.0/24"}]},"limit":100,"page":1}}}},"responses":{"200":{"description":"Successful search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedSearchResponse"},"example":{"items":[{"_id":"example.com|user123","email":"user@example.com","u":"user123","p":"5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8","url":"https://example.com","source":"Anti Public Combo List"}],"total":1500,"total_unlocked":1200,"page":1,"page_size":100}}}},"400":{"description":"Bad request - Invalid parameters or missing required filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"At least one filter must be provided (since, until, domain, email, username, include_fields, or where conditions)"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required - Insufficient credits in wallet","content":{"application/json":{"schema":{"$ref":"#/components/responses/InsufficientCredits"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/breaches/search":{"get":{"summary":"Search for Credentials","tags":["Search"],"description":"Searches for credentials across multiple data sources based on email, domain, or username. Returns occurrence counts and source information. Only one search parameter should be provided per request.","x-production":true,"security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"email","description":"Email address to search for","schema":{"type":"string"},"example":"user@example.com"},{"in":"query","name":"domain","description":"Domain name to search for","schema":{"type":"string"},"example":"example.com"},{"in":"query","name":"username","description":"Username to search for","schema":{"type":"string"},"example":"username123"},{"in":"query","name":"limit","description":"Maximum number of results to return (optional, default 100)","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000},"example":50},{"in":"query","name":"include_plain_credentials","deprecated":true,"description":"Ignored. Response \"items\" (when present) always contain masked emails and hashed passwords (SHA-1, NTLM) only.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful search results with occurrence counts; \"items\" (when present) contain masked emails and hashed passwords (SHA-1, NTLM) only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"},"example":{"query":{"type":"email","value":"user@example.com"},"count":1700,"matches":[{"count":1500,"source":{"name":"Anti Public Combo List","description":"A massive compilation of over 457 million unique email and password pairs.","breached_data":["email","password"],"total_records":3300000000,"date":"2016-12-01"}},{"count":200,"source":{"name":"Twitter database leak","description":"Around 210m customer records were exposed in a data breach.","breached_data":["Email Address","Name","Username","Follower Amount","Created At"],"total_records":210000000,"date":"2021-01-01"}}]}}}},"400":{"description":"Bad request - Missing required search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"At least one of email, domain, or username is required"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required - Insufficient credits in wallet","content":{"application/json":{"schema":{"$ref":"#/components/responses/InsufficientCredits"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/underground/search":{"get":{"summary":"Search across all data types","tags":["Search"],"x-production":true,"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"},"description":"Search query"}],"responses":{"200":{"description":"Search results across all data types","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Group"}},"leaks":{"type":"array","items":{"$ref":"#/components/schemas/Leak"}},"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"channels":{"type":"array","items":{"type":"object","description":"Telegram channel info"}},"messages":{"type":"array","items":{"type":"object","properties":{"group_name":{"type":"string"},"message":{"type":"string"},"date":{"type":"string"}}}},"notes":{"type":"array","items":{"type":"object","properties":{"group_name":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"}}}}}}}}},"400":{"description":"Bad request - missing query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/monitors":{"post":{"tags":["Monitors"],"summary":"Create a new watch list","description":"Creates a new watch list for monitoring specific search terms","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWatchListRequest"},"example":{"search_terms":[{"type":"email","value":"user@example.com","is_regex":false},{"type":"domain","value":"example.com","is_regex":false}],"is_active":true}}}},"responses":{"201":{"description":"Watch list created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchList"}}}},"400":{"description":"Bad request - Missing required fields"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"x-production":true}},"/monitors/{uuid}/search-terms/{searchtermId}/results":{"get":{"tags":["Monitors"],"summary":"Get results for a specific search term in a watch list","description":"INTERNAL: Retrieves the results for a specific search term (by search_term_id) within a given watch list (by uuid).\n","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"uuid","required":true,"schema":{"type":"string"},"description":"UUID of the watch list"},{"in":"path","name":"searchtermId","required":true,"schema":{"type":"string"},"description":"ID of the search term"}],"responses":{"200":{"description":"Array of filtered results for the search term","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"400":{"description":"Bad request - Missing UUID or searchtermId"},"401":{"description":"Unauthorized"},"404":{"description":"Watch list or search term not found"},"500":{"description":"Internal server error"}},"x-internal":true}}}}