Skip to main content
API docs by Redocly

Bronto API (1.0.0)

Download OpenAPI specification:Download

License: Commercial

api-keys

An Application Programming Interface (API) key is a unique identifier. The API Key must be provided as X-BRONTO-API-KEY in headers for the request to be authenticated and authorized by the API server according to the API Key's role. For further information about roles visit [our API Key docs] https://docs.bronto.io/manage/manage-api-keys

Retrieve a list of API keys

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "api_keys": [
    ]
}

Create a new API key

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

The name of the API key to create

roles
required
object

A list of api key role ids

Responses

Request samples

Content type
application/json
{
  • "name": "Production API Key",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production API Key",
  • "created_at": 1710948395538,
  • "api_key": "2ad85149",
  • "roles": [
    ],
  • "tags": {
    }
}

Delete an API key

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
apiKeyId
required
string <uuid>
Example: 41521f35-1b06-41f0-9cdc-9a938b5739d1

The ID of the API key to delete

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "correlation_id": "string",
  • "message": "string"
}

Update an API key

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
apiKeyId
required
string <uuid>
Example: 41521f35-1b06-41f0-9cdc-9a938b5739d1

The ID of the API key to update

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

The new name for the API key

roles
object

A list of api key role ids

Responses

Request samples

Content type
application/json
{
  • "name": "Production API Key",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "correlation_id": "string",
  • "message": "string"
}

context

Context is a REST API resource that allows the retrieval of a specified number of log events (default of 100) around a log event of interest, e.g. when a number of log events were returned by a previous query and you then decide you want to see the 50 log events before one of those returned log events. Log events can be retrieved either before, after, or both before and after the specified log event.

Retrieve contextual information for a given sequence and log

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
from
string non-empty unique
Example: from=550e8400-e29b-41d4-a716-446655440000&from=297bb888-83b1-44e0-8ab6-47879f1275a2

The ids of the logs to search. One of either the from or the from_tags parameters must be specified.

from_tags
string non-empty unique
Example: from_tags=environment:production

The tags to search. Each tag should be in the form <key>:<value>, e.g., environment:production. One of either the from or the from_tags parameters must be specified. If both are specified then from_tags takes precedence, and the from value is ignored. If the key or the value contain a : or = character, then these can be escaped by wrapping the entire key or value in double-quotes ".

timestamp
required
integer
Example: timestamp=1709251200000

The timestamp for the event for which context is being retrieved

limit
integer [ 1 .. 6666 ]
Default: 100
Example: limit=50

The maximum number of events that an event search should return. In a query with a group by, it limits the number of groups returned. It does not affect a statistical search using aggregate functions.

from_sequence
integer
Example: from_sequence=111721913

The starting sequence for which to query data. This is more granular than a timestamp but also requires a from_ts param.

direction
string
Enum: "both" "after" "before"
Example: direction=both

Enum to indicate if results before or after should be retrieved.

Responses

Response samples

Content type
application/json
{}

exports

The Bronto Export API allows you to efficiently download large volumes of log data for further analysis. The data to be exported can be filtered by entering the search parameters "from", "where" and "time_range" as per a normal query in the "search_details" object.

To export data the following steps are required:

  1. Create an export using a POST request, which will return an "export_id", "status" and "progress".
  2. Use the export id to get the status of the export task by sending a GET request, which will return "status" and "progress" with a value of percentage completed. When the export is completed, the "status" will be "COMPLETE"
  3. Once the export task has completed you can download your data using curl (or similar) from the "location" URL returned in the GET response.

Retrieve a list of exports

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "exports": [
    ]
}

Create a new export

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
object or object or object or object (ExportDetails)
One of
from
required
string

The ids of the logs to search separated by a colon (:).

time_range
string

The relative time range for which to query data. Time range supported is from milliseconds to years. For an exact range, use from_ts and to_ts instead.

timeRange
string
Deprecated

The relative time range for which to query data. Time range supported is from milliseconds to years. For an exact range, use from_ts and to_ts instead.

required
integer or string
Deprecated

The starting time (unix time in milliseconds) for which to query data. Must be used together with to_ts. This parameter is not to be used when using time_range.

integer or string

The starting time (unix time in milliseconds) for which to query data. Must be used together with to_ts. This parameter is not to be used when using time_range.

required
integer or string
Deprecated

The ending time (unix time in milliseconds) for which to query data. Must be used together with from_ts. This parameter is incompatible with time_range.

integer or string

The ending time (unix time in milliseconds) for which to query data. Must be used together with from_ts. This parameter is incompatible with time_range.

where
required
string

The where parameter is used to filter the results of your query. See https://docs.bronto.io/core-features/log-search/query-syntax for more details The filter can combine multiple terms using AND, OR, NOT.

Responses

Request samples

Content type
application/json
{
  • "search_details": {
    }
}

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "org_id": "string",
  • "progress": 0,
  • "status": "CREATED",
  • "bytes": 0,
  • "events": 0,
  • "location": "string",
  • "search_details": {
    },
  • "created_at": 0,
  • "modified_at": 0
}

Retrieve an export by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
exportId
required
string <uuid>

The unique identifier of the export to retrieve

Responses

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "org_id": "string",
  • "progress": 0,
  • "status": "CREATED",
  • "bytes": 0,
  • "events": 0,
  • "location": "string",
  • "search_details": {
    },
  • "created_at": 0,
  • "modified_at": 0
}

Delete an export by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
exportId
required
string <uuid>

The unique identifier of the export to delete

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "correlation_id": "string",
  • "message": "string"
}

logs

Logs are a sequence of timestamped log events. Logs can be searched to view events matching a filter or to perform statistical functions on matching events.

Retrieve a list of logs

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

Create a new log

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
logset
string <= 255 characters

The name of the log set

log
required
string [ 1 .. 255 ] characters

The name of the log

Responses

Request samples

Content type
application/json
{
  • "logset": "demo",
  • "log": "http"
}

Response samples

Content type
application/json
{
  • "logset": "demo",
  • "log": "firewall",
  • "log_id": "14b5977f-7a80-40ca-bb79-eca6c2abdb34",
  • "is_system_generated": false,
  • "tags": {
    },
  • "drop_events": 0,
  • "level": "trace"
}

search

The REST API for searching data uses queries based on a subset of SQL, with the syntax as per https://docs.brontobytes.io/core-features/log-search/query-syntax/.

There are two types of search:

  • event search: allows you to specify a filter and view the matching events returned in the response. The response will be paginated if more than 50 matching events are returned.
  • statistical search: allows you to analyse events using a range of aggregate functions, such as count(), which return a number.

Execute a query

The REST API for searching data uses queries based on a subset of SQL, with the syntax as per https://docs.brontobytes.io/core-features/log-search/query-syntax/.

There are two types of search:

  • event search: allows you to specify a filter and view the matching events returned in the response. The response will be paginated if more than 50 matching events are returned.
  • statistical search: allows you to analyse events using a range of aggregate functions, such as count(), which return a number.
Authorizations:
ApiKeyAuthBearerAuth
query Parameters
from
string non-empty unique
Example: from=550e8400-e29b-41d4-a716-446655440000&from=297bb888-83b1-44e0-8ab6-47879f1275a2

The ids of the logs to search. One of either the from or the from_tags parameters must be specified.

from_tags
string non-empty unique
Example: from_tags=environment:production

The tags to search. Each tag should be in the form <key>:<value>, e.g., environment:production. One of either the from or the from_tags parameters must be specified. If both are specified then from_tags takes precedence, and the from value is ignored. If the key or the value contain a : or = character, then these can be escaped by wrapping the entire key or value in double-quotes ".

time_range
string
Examples:
  • time_range=Last 800 milliseconds -
  • time_range=Last 10 seconds -
  • time_range=Last 2 days -
  • time_range=Last 3 weeks -

The relative time range for which to query data. Time range supported is from milliseconds to years. For an exact range, use from_ts and to_ts instead.

from_ts
integer
Example: from_ts=1709251200000

The starting time (unix time in milliseconds) for which to query data. Must be used together with to_ts. This parameter is not to be used when using time_range.

to_ts
integer
Example: to_ts=1711390455601

The ending time (unix time in milliseconds) for which to query data. Must be used together with from_ts. This parameter is incompatible with time_range.

where
string
Examples:
  • where=ip=10.0.0.1 -
  • where=count(*) -
  • where=sum(payload_size) -
  • where=count(*), sum(payload_size) -
  • where=@raw -
  • where=payload_size, status, client_ip -

The where parameter is used to filter the results of your query. See https://docs.bronto.io/core-features/log-search/query-syntax for more details The filter can combine multiple terms using AND, OR, NOT.

select
string
Example: select=message

The select parameter selects values of one or more specified keys and can be considered to be equivalent to returning columns from a table. It can select keys either by name, e.g. query params with select=ip_address or with an aggregate function (count, max, min, avg, sum) on the values of the specified key, e.g. query params with select=count(ip_address). Multiple selects can be used and they would separated by & in the query param, e.g. &select=count(ip_address)&select=count(hostname). The following internal columns are always available: @time, @origin & @raw

groups
string
Example: groups=user&groups=ip

The groups parameter specifies a key to use to arrange the results returned by an aggregate function, (such as count, max, min, avg, sum) into groups of values. The aggregate function returns a single value for each group. Multiple groups can be specified in the request if separated by &, e.g. query params with &groups=customer_id or &groups=customer_id&groups=hostname.

limit
integer [ 1 .. 6666 ]
Default: 100
Example: limit=50

The maximum number of events that an event search should return. In a query with a group by, it limits the number of groups returned. It does not affect a statistical search using aggregate functions.

num_of_slices
integer
Default: 10
Example: num_of_slices=50

The number of buckets to break the time series results up into.

from_sequence
integer
Example: from_sequence=111721913

The starting sequence for which to query data. This is more granular than a timestamp but also requires a from_ts param.

most_recent_first
boolean
Example: most_recent_first=true

Flag to indicate order in which results should be returned.

Responses

Response samples

Content type
application/json
{
  • "explain": {
    },
  • "result": [],
  • "events": [
    ],
  • "groups": [
    ],
  • "groups_series": [
    ],
  • "metadata": {
    },
  • "totals": { },
  • "pagination": {},
  • "links": []
}

top-keys

Top-Keys is a REST API resource that allows you to easily retrieve the top keys for a specific log.

Get the top keys for a specific log id

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
log_id
string <uuid>
Example: log_id=550e8400-e29b-41d4-a716-446655440000

The ids of the logs to retrieve the top keys for. If no log ids are specified, then top keys are returned for all logs.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

usage

Usage is a REST API resource that allows you to easily track your Bronto usage by retrieving usage data relating to data ingestion and amount of data searched, and allowing you to drill down for a specific dataset over a defined timeframe.

Get the usage over a period of time for a log id.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
time_range
string
Examples:
  • time_range=Last 10 minutes -
  • time_range=Last 2 days -
  • time_range=Last 3 weeks -

The relative time range for which to calculate usage data. Time range supported is from minutes to years. For an exact range, use from_ts and to_ts instead.

from_ts
integer
Example: from_ts=1709251200000

The starting time (unix time in milliseconds) for which to calculate usage data. Must be used together with to_ts. This parameter is not to be used when using time_range.

to_ts
integer
Example: to_ts=1711390455601

The ending time (unix time in milliseconds) for which to calculate usage data. Must be used together with from_ts. This parameter is incompatible with time_range.

usage_type
string
Enum: "ingestion" "search" "export"

The type of usage to query.

limit
integer
Example: limit=10

Returns the top N logs based on the usage. If not provided, the default limit is 50. The maximum limit is 100.

num_of_slices
integer
Example: num_of_slices=10

The num_of_slices parameter defines how the time range is divided into intervals. It is optional, and if not provided, a default value is applied. The default number of slices is 1 minute granularity for up to 12 hours time range and 20 minutes granularity for longer than 12 hours time range up to 720 slices. - default for 20 minutes time window: 20 slices - default for 12 hour time window: 720 slices - default for 1 day time window: 72 slices (1 slice per 20 minutes) - default for 10 days time window: 720 slices (1 slice per 20 minutes) - default for 30 days time window: 720 slices (max number of slices allowed)

Responses

Response samples

Content type
application/json
{
  • "name": "Usage",
  • "filter": "event_type='log_usage'",
  • "stat": "SUM",
  • "key": "bytes_total",
  • "is_exact": true,
  • "groups_series": [
    ]
}

users

Users are given specific roles, where each role determines the user's permissions within the application. Those roles are as follows:

  • "Admin" role has permission for all actions on all entities in the application.
  • "Standard" role allows Read/Write and Delete actions on entities in non-sensitive areas of the application.
  • "ReadOnly" role allows only read actions and only on entities in non-sensitive areas of the application.

Retrieve a list of users

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Create a new user

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
first_name
required
string [ 1 .. 255 ] characters

The user's first name

last_name
required
string [ 1 .. 255 ] characters

The user's last name

email
required
string <email>

The user's email address

roles
required
Array of strings

A list of role ids

Responses

Request samples

Content type
application/json
{
  • "first_name": "Alice",
  • "last_name": "Smith",
  • "email": "alice@company.com",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john@company.com",
  • "roles": [
    ],
  • "last_logins": {
    },
  • "tags": {
    }
}

Get a single user by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string <uuid>
Example: 41521f35-1b06-41f0-9cdc-9a938b5739d1

The unique identifier of the user to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john@company.com",
  • "roles": [
    ],
  • "last_logins": {
    },
  • "tags": {
    }
}

Delete a user by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string <uuid>

Unique identifier of the user to delete

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "correlation_id": "string",
  • "message": "string"
}

Updates a user

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
userId
required
string <uuid>

Unique identifier of the user to update

Request Body schema: application/json
required
first_name
string [ 1 .. 255 ] characters

The user's first name

last_name
string [ 1 .. 255 ] characters

The user's last name

roles
Array of strings

A list of role ids

Responses

Request samples

Content type
application/json
{
  • "first_name": "Alice",
  • "last_name": "Smith",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john@company.com",
  • "roles": [
    ],
  • "last_logins": {
    },
  • "tags": {
    }
}