In order to query data or launch exports, you need to have access to a Botify project.
If you are not a Botify customer yet, feel free to contact our sales team and request a demo.
If you are, you should already be good to go!
Scoping your requests to a specific resource
Project object is at the root of your Botify setup. All of the other objects you will manipulate are tied to it (crawls, collections, etc).
Project is identified by two properties:
- username: the username of its owner
- slug: the sanitized, URL-friendly equivalent of the project name
Most of the endpoints you will discover throughout this documentation are tied to an instance of this
Project object. This is symbolized by a
Tip: How to quickly find the prefix to use?
The application uses the same prefix as the API, so you can simply copy/paste it from the URL when navigating in the app.
Example: In RealKeywords, the URL would look like
https://app.botify.com/customer01/my-website/keywords/..., so you could copy the
/customer01/my-website/prefix and use it for your queries.
Let's take a project named "My Website" owned by "customer01":
slugwould be something like
To run a BQL query for this project, you would use the https://api.botify.com/v1/projects/customer01/my-website/query endpoint.
Getting your analysis slug
One of Botify's product is SiteCrawler, in which your website will be crawled and analyzed. It's important to note that, in the specific case of Botify's API, we interchangeably use the wording crawl and analysis, even though they ultimately represent different concepts.
A project may contain many analyses, which are refered to by a slug and the project identifier.
An analysis slug commonly looks like
When multiple crawls were launched the same day, an integer suffix is added to the slug
YYYYMMDD-X, incremented as needed.
Example: To retrieve the latest analysis slug of your project, you can access:
which will load SiteCrawler with your latest analysis.
Once loaded, the URL contains a parameter named
analysisSlug. In the image below, the analysis slug is
Authentication with the API
Because your data is valuable, all API requests must be authenticated.
Authentication is performed via the means of an API token. It helps the API determine who you are and what you have access to.
Retrieving your API token
It is displayed on your profile page: https://app.botify.com/account/ (which will redirect you to
<username> is your actual username).
Simply scroll down to the "Tokens" panel, and you will find your API token.
Note: If you ever needed to regenerate your token (after it was leaked by mistake, or after the departure of a collaborator), you can do it right on this page.
Using the token with API calls
In order for your request to be properly authenticated, you must pass your API token in the
Authorization HTTP header.
curl --request POST \ --url https://api.botify.com/v1/projects/<username>/<project>/query \ --header 'Content-Type: application/json' \ --header 'Authorization: Token <my redacted token>' \ --data 'BQL_QUERY'
You can access our APIs using any HTTP-compatible client:
Updated almost 2 years ago
Run your first BQL query following these guides