API

API Docs

Authentication

Send the API token in the X-Api-Key header.

The header value must be a Base64-encoded token.

Getting the token

Open Profile.

Generate the token:

1. Open Profile

2. Click Create Token

3. Choose at least one permission for the token

4. Set expiration date

5. Set token name

6. Click Create

Encode the created token to Base64:

1

echo -n "<your-token>" | base64

Use the resulting Base64 string as the X-Api-Key header value.

Pagination Query Builder for API

BotBye API supports Keyset-based pagination, which allows for efficient page retrieval.

This method is controlled by the following query parameters:

• cursor (Optional): a cursor for pagination.
  • first (number): Number of items to retrieve after the cursor. Default is 20.
  • after (string): Pointer to the item after which the items are to be retrieved.
  • last (number): Number of items to retrieve before the cursor.
  • before (string): Pointer to the item before which the items are to be retrieved.
• where (Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes).
  • predicate (string): The filtering condition (e.g., gte, lte, eq for a leaf or and, or for a branch). For possible values, see below.
  • operands (string): A list of nested conditions (used only for branches, such as and, or).
  • fieldPath (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list). For possible values, see below.
  • value (string): The value to compare against the field (used only for a leaf).
• order_by (Optional): property by which to order by.
  • fieldPath (string): name of order field. For possible values, see below.
  • direction (string): ASC or DESC
• total (Optional): when set to true, includes total matched records in pageInfo.total.

Query parameters

where

Available fieldPath values depend on the endpoint. See the specific endpoint schema in API Docs.

Possible predicate values

Usage Examples

Simple Condition (Leaf Node)

1
2
3
4
5

{
  "fieldPath": "name",
  "predicate": "eq",
  "value": "Test"
}

returns objects where the name field is Test

Compound Condition (Branch Node)

In the compound condition, the and predicate is used to combine multiple conditions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "predicate": "and",
  "operands": [
    {
      "fieldPath": "project_id",
      "predicate": "eq",
      "value": "c415a474-be24-11eb-8529-0242ac130003"
    },
    {
      "fieldPath": "country",
      "predicate": "eq",
      "value": "DEU"
    }
  ]
}

returns objects that match all conditions in the operands array

Incorrect Use of a Branch with value

The incorrect example demonstrates an error when the value field is used incorrectly in a branching where. Can only be predicate(and/or) and operands.

1
2
3
4
5
6
7
8
9
10
11
12

{
  "predicate": "and",
  "operands": [
    {
      "fieldPath": "name",
      "predicate": "eq",
      "value": "Test project"
    }
  ],
  "value": "25"
  // Error: `value` should not be used in branches
}

order_by

order_by is used to sort objects by the specified fields using the field path described in where.

1
2
3
4
5
6

[
  {
    "fieldPath": "remote_addr",
    "direction": "DESC"
  }
]

returns objects sorted by descending IP address

cursor

The cursor parameter is used to specify the selection start point for page navigation.

1
2
3
4

{
  "first": 20,
  "after": "MjAyNC0wNi0wM1QxMzoxNjoyNi41MTNaLDAxOTBkOWYxLTQ2OTEtNzIyYy1hNzlmLWQ5ZmQ0NmJmMDY1YQ=="
}

first and last control page size. The page size must be between 1 and 100.

Use either after or before, but not both.

total

Set total=true to include the total number of matching records in pageInfo.total.

If total is omitted, pageInfo.total is -1.

Full request example

Replace the path and field names with values supported by your endpoint in API Docs.

1
2

GET /api/v1/{your-endpoint-path}?cursor=%7B%22first%22%3A20%2C%22after%22%3A%22MjAyNC0wNi0wM1QxMzoxNjoyNi41MTNaLDAxOTBkOWYxLTQ2OTEtNzIyYy1hNzlmLWQ5ZmQ0NmJmMDY1YQ%3D%3D%22%7D&where=%7B%22predicate%22%3A%22and%22%2C%22operands%22%3A%5B%7B%22fieldPath%22%3A%22project_id%22%2C%22predicate%22%3A%22eq%22%2C%22value%22%3A%22c415a474-be24-11eb-8529-0242ac130003%22%7D%2C%7B%22fieldPath%22%3A%22country%22%2C%22predicate%22%3A%22eq%22%2C%22value%22%3A%22DEU%22%7D%5D%7D&order_by=%5B%7B%22fieldPath%22%3A%22remote_addr%22%2C%22direction%22%3A%22DESC%22%7D%5D&total=true
X-Api-Key: <base64-encoded-api-token>