API basics

Last updated: Nov 4, 2026

On the Fluid Attacks platform, you can make requests to its GraphQL API. Before you do that, get some basic knowledge of this query language.

Then, use this guide. It tells you how to authenticate and how to start to explore the API.

Authenticate to use the API

You can authenticate to the Fluid Attacks API from the GraphiQL playground or by HTTP requests in code. This guide tells you about two ways to authenticate in the GraphiQL playground.

Authentication with Fluid Attacks' platform login

You can authenticate with the login of the Fluid Attacks platform:

1. Log in to the platform.
2. Access the API.

Then, write your queries. Click the play icon to run them.

Authentication with Fluid Attacks' platform API token

You can authenticate to the Fluid Attacks API with a token, which you add on the Fluid Attacks platform. Do the steps below.

1. Log in to the Fluid Attacks platform at app.fluidattacks.com.

2. Click the user menu.

3. Select the API token option.

   

4. In the pop-up window, click Add token.

   

5. Type a name for your token.

6. Select an expiration date for your token (a maximum of six months from the current date).

   

   You can have a maximum of two active API tokens.

7. Click Confirm. The window shows your token as asterisks. If you want, click View to show it.

   

8. Click Copy. Keep this token in a safe location. After you close the pop-up window, the platform does not show it again. When the copy is successful, the platform shows a message for a short time.

   

9. Go to the GraphiQL playground.

10. Select the Headers tab at the bottom.

    

11. In Headers, type {"authorization":"Bearer YOUR_TOKEN_GOES_HERE"}. (Replace YOUR_TOKEN_GOES_HERE with your token.)

12. Write your GraphQL queries in the top area.

13. Click the play icon to run them.

Examples of a simple query

These examples show how to make a simple query to the Fluid Attacks API with Python, JavaScript, and Bash. This query gets the username and email of the current user.

All the examples use the POST method to send the GraphQL query to the API endpoint. To learn about this method, read the official GraphQL documentation.

Python

import requests
query = """
{
  me {
    userName
    userEmail
  }
}
"""
token = "YOUR_TOKEN_GOES_HERE"

response = requests.post(
  "https://app.fluidattacks.com/api",
  json={"query": query},
  headers={"authorization": f"Bearer {token}"},
)
print(response.json())

JavaScript

const response = await fetch("https://app.fluidattacks.com/api", {
  headers: {
    "content-type": "application/json",
    authorization: "Bearer YOUR_TOKEN_GOES_HERE",
  },
  body: JSON.stringify({ query: "{ me { userName userEmail }}" }),
  method: "POST",
});
console.log(await response.json());

Bash

curl \
  --request POST \
  --url https://app.fluidattacks.com/api \
  --header "content-type: application/json" \
  --header "authorization: Bearer YOUR_TOKEN_GOES_HERE" \
  --data '{"query": "{ me { userName userEmail }}"}'

Revoke API token

If an API token expired or if you cannot find it, you can revoke it. To revoke the token, follow these steps:

1. Log in to the Fluid Attacks platform at app.fluidattacks.com.

2. Click the user menu.

3. Select API token.

4. Click Revoke.

   

   If you revoke an active token that you used in the past seven days, a warning message shows the last time that you used it.

   

   After you revoke a token, it becomes invalid. Its expiration date does not change this. You cannot use it to authenticate. The integrations that use the revoked token must have a new one to work again.

5. Click Confirm.

Access playground docs

The GraphiQL playground has built-in documentation to help you explore the API:

1. Go to the API page.

2. Click the book icon on the left side of the playground.

   

3. Examine the available queries, mutations, and schema types.

   

Paginated fields

The Fluid Attacks API uses paginated and non-paginated lists. Non-paginated lists give all the available results directly, as a normal list, between square brackets. The screenshot below shows an example.

Paginated lists, which usually have the suffix Connection, give only a specified number of results and a "cursor". You can include this cursor in the next requests to go to the next pages.

Remember these differences when you build integrations that must get all the information in a paginated field. For more information, read the official pagination documentation of GraphQL.

Paginated fields give a maximum of 500 results for each request. If you ask for more than 500 results, the API returns an error and no data. Thus, ask for 500 results or fewer for each page. Then, use the cursor to get the next page.

This example helps you understand pagination. It gets the first ten vulnerabilities of a group with the name Narrabri. The screenshot below shows the query.

Examine the terminal. If there is a next page, the last item of the query shows hasNextPage and endCursor. hasNextPage tells you that there is a next page, and endCursor gives its cursor token.

To see the next page, give the cursor token as the after argument in your next query.

Continue to send requests with the updated after argument until hasNextPage is false. This value tells you that you got all the pages. Read other examples in the GraphQL documentation.

Rate limits

The Fluid Attacks API has a rate limit that is different for each authentication method. Requests with token authentication get a much higher limit. If you go above this limit, you get an HTTP 429 (Too Many Requests) error response. The response includes a retry-after header. This header tells you how long to wait before you send another request.

This Python script shows how to control this condition:

import requests
from time import sleep
query = """
{
  me {
    userName
    userEmail
  }
}
"""
token = ""
def request():
    while True:
        response = requests.post(
          "https://app.fluidattacks.com/api",
          json={"query": query},
          headers={"authorization": f"Bearer {token}"},
        )
        if response.status_code == 429:
            seconds = response.headers["retry-after"]
            sleep(seconds + 1)
        else:
            break
    return response
response = request()
print(response.json())

This solution can be different for each HTTP client library or language. Fluid Attacks also recommends that you wait one more second than the value of the header.

Temporary network errors

The Fluid Attacks API can sometimes have temporary network problems, for example, timeouts because of high demand, or connection failures.

To make your integration more resilient, add a retry mechanism for failed requests. This mechanism is very important for mission-critical processes that use the API. This Python script is a small example:

MAX_RETRIES = 10

def request():
    while True:
        response = requests.post(
            "https://app.fluidattacks.com/api",
            json={"query": query},
            headers={"authorization": f"Bearer {token}"},
        )

        if response.status_code == 429:
            seconds = response.headers["retry-after"]
            sleep(seconds + 1)
        elif response.status_code >= 500:
            retries += 1
            if retries == MAX_RETRIES:
                break
            sleep(retries)
        else:
            break

    return response

This solution can be different for each HTTP client library or language.

Fluid Attacks' platform API response status

The Fluid Attacks platform API uses standard HTTP status codes to show the success or failure of your requests. These are some of the most frequent codes:

Response times

With GraphQL, you can request a large quantity of data in one request, but the response time increases with the quantity of data. Thus, you can divide your queries into different requests when it is necessary.