API Documentation

You need a valid API key to use API. You can register for a free account and get one here: Register


Premium Users
  • For premium users there are no limits on the results someone can go through.
  • The is however a limit on how many files you can get on each page. This limit is 1000. You can however read all the results page by page. See below documentation for details.
Registered Users
  • For free registered users, the same limits as the search apply, explained here: Packages.


  • For the API to function properly, all GET parameters of the request url should be url encoded. For example the space character " " should be replaced with "%20". You can use this tool to url encode your parameters.


curl "https://buckets.grayhatwarfare.com/api/v1/buckets[/start[/limit]]?access_token=api-key"


  • start - buckets offset (optional)
  • limit - how many buckets to bring (optional)


  • buckets_count - how many buckets we collected
  • start - buckets offset
  • limit - how many buckets in response
  • buckets - json array with buckets (id, bucket)


Give me the first ten of buckets
Give me the second ten of buckets
Get the first 10 buckets matching the keywords "test"

Keep in mind that GET parameters values should be url encoded (?)

List contents of bucket with id 5, starting from 0, with 100 limit.
List contents of bucket with id 5, that contains the keywords csv starting from 0, with 100 limit.

Keep in mind that GET parameters values should be url encoded (?)

List contents of bucket with id 5, that contains the keywords csv in full path, starting from 0, with 100 limit.

Keep in mind that GET parameters values should be url encoded (?)

Search Files

curl "https://buckets.grayhatwarfare.com/api/v1/files[/keywords[/start[/limit]]]?access_token=api-key[&order=size&direction=asc|desc][&extensions=list,of,extensions][&stopextensions=list,of,stop,extensions]"

Basic Usage


  • keywords - your query (optional)
  • start - files offset (where to start from - optional)
  • limit - how many files to bring (optional)
  • sorting
    • Order by size desc: order=size&direction=desc
    • Order by size asc: order=size&direction=asc
  • Filename Extensions
    • Accepts a comma separated text of extensions.
    • Can be combined with all the above filters.
    • User can filter only by extensions.
    • Search only Excel and Word Documents: extensions=docx,xlsx
    • Exclude csv and txt files: stopextensions=csv,txt
  • Regular Expression - regexp=1 - Read more about regular expressions below, see basic overview here or view the Regex documentation here
  • Regular Expression - Do not autocorrect regex - noautocorrect=1 - Do not try automatically correct my regex. (?)


  • keywords - your query
  • results - how many results we have
  • start - offset offset
  • limit - how many files in response
  • order - if specified (size)
  • direction - if specified (asc/desc)
  • files - json array with files (id, bucket, filename, fullPath, url, size)


Search filenames containing "mp3" (only filenames not paths.)
Search filenames containing "mp3" (Full-Path search, filename + paths)
Search filenames containing "mp3" and exclude keywords jazz and ntalaras
Search filenames containing "mp3" and bring me 10 files starting from 10
Search filenames containing "mp3" and sort results by size in descending order
Search for excel and csv filenames containing "music" (with extension mp3 and flac)
Search for filenames containing "video" and exclude video files (with filename extension mp4,avi,mpg)

Regular Expression

The below is the outline of the regular expressions parameters. To more about regular expressions, what we support and how to create your regular expressions, follow this link: Regular Expressions Help

To search as a regular expression you have to replace the keyword in file search, with the base64 of the regexp you want to search for. For example if you want to search for .*dump.*(gz|tar|zip) Do the following:



  • Take the simple search url: https://buckets.grayhatwarfare.com/api/v1/files/{keywords}?access_token={apiKey}
  • Add regexp=1 in the end: https://buckets.grayhatwarfare.com/api/v1/files/{keywords}?access_token={apiKey}&regexp=1
  • Convert your regexp to base64 and put in in the {keywords} placeholder: https://buckets.grayhatwarfare.com/api/v1/files/{keywords}?access_token={apiKey}&regexp=1

Generating the base64 value of some string is included in all languages. You can also use the textbox above to generate it for you. The link is automatically updated. For a more comprehensive regular expression documentation please study the Regular Expressions Docs.

The regular expression api will be revised. In case of error, please retry the same request up to 5 times before giving up.


Copyright © 2018-2020 grayhatwarfare.com All rights reserved. Hand-crafted & made with with Symfony PHP Framework, golang and all databases known to man 😉