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

The 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).

A 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 /<username>/<slug>/... prefix.

📘

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.

Example:
Let's take a project named "My Website" owned by "customer01":

• The username would be customer01
• The slug would be something like my-website

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 YYYYMMDD.
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:
https://app.botify.com/USERNAME/PROJECTSLUG/crawl
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 20210308.

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 https://app.botify.com/<username>/account (where <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.

Example:

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'

Tools

You can access our APIs using any HTTP-compatible client:

• a terminal client, like cURL in the example above
• a more user-friendly tool like Insomnia or Postman