swagger: '2.0'
schemes: [ https ]
host: api.logz.io
x-servers:
- url: https://api.logz.io
description: US East (Northern Virginia)
- url: https://api-au.logz.io
description: Asia Pacific (Sydney)
- url: https://api-ca.logz.io
description: Canada (Central)
- url: https://api-eu.logz.io
description: Europe (Frankfurt)
- url: https://api-uk.logz.io
description: Europe (London)
basePath: /
produces: [ application/json ]
consumes: [ application/json ]
info:
description: >-
# Introduction
This API is documented using the **OpenAPI 2.0** specification.
The OpenAPI Specification file is also [available for download](https://github.com/logzio/logz-api/blob/master/examples/logzio-public-api.yml)
# Automation
You can automate most of our APIs using our [Terraform provider](https://docs.logz.io/integrations/terraform/).
# Account region and API URL
To find your account region, sign in to Logz.io and look at the URL in the address bar.
Your API URL has the same two-letter code that you see in the address bar when you're logged in.
For more information, see [Account region](https://docs.logz.io/user-guide/accounts/account-region.html).
# Authentication
The Logz.io API is available to Pro and Enterprise plan subscribers.
You can generate and delete API tokens in your [Logz.io account](https://app.logz.io/#/dashboard/settings/manage-tokens/api).
# Rate limiting
API call and response rates are limited to 100 concurrent API requests per account.
To verify your rate limits or request changes to your plan, please contact your account manager or the <a class="intercom-launch" href="mailto:[email protected]">Customer Success Team</a>.
# Compression
Compression is supported and recommended for all API calls. To enable compression for API responses, add the following request header:
Header Name: Accept-Encoding
Header Value: deflate, gzip
Compression is STRONGLY RECOMMENDED for 'Search' and 'Scroll' APIs, due to their potentially large response sizes.
title: Logz.io API
termsOfService: 'https://logz.io/about-us/terms-of-use/'
contact:
email: [email protected]
url: https://docs.logz.io/
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
securityDefinitions:
X-API-TOKEN:
description: >-
You can manage your API tokens from the [Logz.io API tokens](https://app.logz.io/#/dashboard/settings/manage-tokens/api) page.
API tokens are account-specific. You will need to be logged into the relevant Log Management or SIEM account to view the API tokens associated with it.
To manage your API tokens, log into the relevant account in your Logz.io platform, click the gear in the top-right menu, and select [**Tools > Manage tokens > API tokens**](https://app.logz.io/#/dashboard/settings/manage-tokens/api).
It's important to keep your tokens secure. API tokens carry privileges to make changes to users and accounts, so if you believe an API token has been compromised, delete it, and replace it with a new token in your integrations.
type: apiKey
in: header
name: X-API-TOKEN
security:
- X-API-TOKEN: []
tags:
- name: Metrics gateway
description: >-
Metrics API Gateway to supported endpoints. In the context of this API, "*Grafana*" refers to the Logz.io fork of Grafana, thus this gateway provides support for the APIs of the Logz.io fork of Grafana and for some of the open source Grafana APIs. Read more about the fork created by Logz.io [here.](https://logz.io/about-us/forked-statement/)
**Note:** Run these endpoints with an API token belonging to the main Log Management account associated with your Metrics account.
- name: Who am I
- name: Manage time-based log accounts
description: >-
Use these API requests to manage time-based log accounts:
* Create, update, or delete a sub account.
* Allocate daily capacity to the main account and/or sub accounts.
* Retrieve account activity stats and/or account configuration details.
### Flexible storage & shared volume
Flexible storage and shared volume allow accounts to share indexing capacity.
To enable shared volume, go to the [Manage accounts page](https://app.logz.io/#/dashboard/settings/manage-accounts) in the Logz.io app and toggle the button **Use flexible volume** to turn it on.
To determine whether flexible storage is enabled, run a `Get` request to retrieve account details.
* If `isFlexible` is true, flexible storage is enabled and every account has reserved capacity set by the parameter `reservedDailyGB`.
* If false, flexible storage is disabled and the parameter `reservedDailyGB` is null.
- name: Search logs
description: >-
Use the Elasticsearch Search API DSL query language to search your Logz.io data.
To ensure system performance and data availability, we've introduced some limitations to the original Elasticsearch specification. These limitations are detailed in the applicable API calls below.
- name: Deployments
description: >-
Send deployment logs by API to automatically correlate exceptions with service deployments directly in your Logz.io Exceptions tab.
- name: Insights
description: >-
Logz.io monitors your logs for Insights to help you preempt issues and alert you of potential problems.
There are two types of Insights:
* LOGCEPTION - Application errors and exceptions identified in the stack trace.
* PUBLIC_CI - Cognitive Insights correlate your logs with vulnerabilities and issues that are trending in the open source community.
You have the option to set up an alert so you can get notified of the details when new or recurring insights are spotted in your system.
**Note:** This endpoint requires permissions that must be set by our Support team. Please email [[email protected]](mailto:[email protected]) for assistance.
- name: Retrieve audit trail
- name: Connect to CloudTrail
description: Establish a connection to ship logs to the Logz.io observability platform via an S3 bucket. Supports CloudTrail logs.
- name: Connect to S3 Buckets
description: >-
Establish a connection for the Logz.io fetcher to fetch logs to the Logz.io observability platform via an S3 bucket. Supports ELB, S3 Access, CloudFront, VPC Flow logs.
If you're looking to fetch CloudTrail logs, use the designated endpoints.
Authentication can be established with either S3 secret credentials or ARNs (for AWS IAM Roles). Authentication with S3 Secret Credentials is supported for backward compatibility. Authentication with ARNs (for IAM Roles) is strongly recommended.
- name: Manage notification endpoints
description: >-
Logz.io can send notifications to your preferred workspaces, such as Opsgenie, BigPanda, PagerDuty, and Slack.
Notifications are typically sent when alerts are triggered, when a user shares a Kibana object,
or when Logz.io Insights identifies new exceptions in your logs.
Use these API endpoints to create, update, or delete notification endpoints. If you configure a custom endpoint,
you can configure the notification message body.
Otherwise, you can use any of the available preconfigured endpoints.
- name: Import or export Kibana objects
- name: Manage log shipping tokens
description: >-
Use these API endpoints to create, update, retrieve, or delete log shipping tokens.
- name: Drop filters
description: >-
Drop filters provide a solution for filtering out logs before they are indexed in your account to help lower costs and reduce account volume.
Drop filters evaluate logs for exact field:value matches. Any log results that match active drop filters will not be indexed. This means they will not appear in your Kibana account, will not be searchable, trigger alerts, or appear in dashboards.
Archiving is not affected by drop filters. Logs dropped by drop filters will still be archived, if archiving is configured for the account. With archiving configured, you can readily use drop filters to reduce logging bulk and restore the logs in the event that they become relevant.
- name: Manage shared tokens
description: >-
You can share Kibana visualization and dashboard snapshots using shared tokens. Snapshots are stored for 30 days and automatically deleted afterwards.
Token filters are available to help you control what data to expose.
**Note:** Shared token endpoints require permissions that must be set by our Support team. Please email [email protected] for assistance.
- name: Manage API tokens
description: >-
You can manage API tokens for sub accounts.
- name: Logz.io snapshots
- name: Manage users
- name: Alerts
description: >-
Logz.io alerts use a Kibana search query to continuously scan your logs and alert you when a certain set of conditions is met. The simplest alerts can use a simple search query or a particular filter, but others can be quite complex and involve several conditions with varying thresholds.
When alerts trigger, they write event logs. Event logs of triggered alerts are always available and searchable in Kibana - just filter for `_exists_:logzio-alert`. But you also have the option to add notifications, and control their contents, format, and who they are sent to.
For the deprecated alerting version, please see our [public GitHub project](https://github.com/logzio/public-api/tree/master/alerts).
- name: Security rules
description: >-
Security rules help you connect the dots between your data sources and events that could indicate a security threat or breach.
Your Cloud SIEM account comes pre-configured with security rules for different attack types and security use cases. These built-in rules are protected, and there are limitations on the changes that can be made to them. Pre-configured rules can be updated by adding notification endpoints (like email or Slack), changing trigger thresholds and severities, and adding tags, as described in detail in the endpoint.
You can also create new security rules to supplement the built-in rules.
- name: Security account
description: >-
A security account with SIEM allows you to use the SIEM platform. You can create a SIEM account using an API call.
- name: Security events
description: >-
A security event is logged whenever a security rule triggers in your [Logz.io Cloud SIEM account](https://app.logz.io/#/dashboard/security/rules/rule-definitions?from=0&sortBy=updatedAt&sortOrder=DESC).
Your Logz.io Cloud SIEM is pre-loaded with hundreds of security rules created and maintained by Logz.io's security analysts. The list continues to be expanded and updated on a regular basis. You can also add your own security rules.
To investigate into security events, you can begin by running a bulk query to fetch security event logs, either with or without applying filtering criteria. This query returns all of the events that match the query parameters and can potentially fetch events going back many months. Whenever you encounter a particular event you would like to further investigate, you can run the drilldown query to fetch the logs that triggered the security event to delve deeper into the event details.
These queries can be used to integrate with an automated response solution such as Cortex xSOAR or simply to understand your security posture and identify suspicious activity in your accounts.
- name: Archive logs
description: >-
You can archive logs to an AWS S3 bucket or Azure Blob Storage. Archiving gives you the option to restore logs and query them after they have expired from your time-based account.
You can use the following endpoints to retrieve, set up, test, and update an account's archive settings.
Note: Logs are archived before they are indexed and analyzed by Logz.io. If you are using drop filters, note that dropped logs will still be archived.
- name: Restore logs
description: >-
You can restore data from your active archiving account, whether an AWS S3 bucket or Azure Blob Storage. Restoring data gives you the option to query logs after they have expired from your time-based account.
You can use the following endpoints to initiate a new restore process, retrieve, set up, test, and update an account's archive settings.
Note: Logs that are dropped by drop filters are still archived and can be restored. You can temporarily disable drop filters to restore the data.
- name: Lookups
description: >-
Lookups are custom lists of values that allow you to easily filter by large lists in Kibana.
Instead of adding a long list of elements to your query, you can create lookup lists and filter by them using the operators `in lookups`/`not in lookups`.
For this purpose, all of the values in a lookup list should be mapped to the same field in Kibana. [Learn more in the user guide](/user-guide/lookups/)
- name: Grafana alerting
description: >-
To create an alert, use the Grafana dashboards API.
- name: Authentication groups
description: >-
Before you can use Authentication Groups API, Logz.io support will need to enable [SSO](https://docs.logz.io/user-guide/users/single-sign-on/) for your account.
x-tagGroups:
- name: Log Monitoring
tags:
- Search logs
- Alerts
- Deployments
- Insights
- Logz.io snapshots
- name: Cloud SIEM
tags:
- Security account
- Security rules
- Security events
- Lookup lists
- name: Account administration
tags:
- Manage users
- Manage metrics account
- Associated accounts
- Authentication groups
- Who am I
- Manage time-based log accounts
- Manage shared tokens
- Manage API tokens
- Manage notification endpoints
- Import or export Kibana objects
- name: Manage data shipping
tags:
- Manage log shipping tokens
- Drop filters
- Archive logs
- Restore logs
- Parsing
- Delete object API
- name: Data security
tags:
- Retrieve audit trail
- name: Connect to AWS resources
tags:
- Connect to CloudTrail
- Connect to S3 Buckets
- name: Metrics API Gateway
tags:
- Grafana contact points
- Grafana data source
- Grafana alerting provisioning
- Grafana silence management
- Grafana annotations
- Grafana dashboards
- Grafana dashboard search
- Grafana snapshots
- Grafana get all folders
description: Metrics API Gateway to supported endpoints.
paths:
# ::::: PROMETHEUS
/v1/metrics/prometheus/api/v1/query:
get:
operationId: 'GetInstantQuery'
summary: 'Evaluates an instant query at a single point in time'
description: |
Retrieve data by submitting a GET request with query parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Query
parameters:
- in: query
name: query
type: string
required: true
description: 'Prometheus expression query string.'
- in: query
name: time
type: string
required: false
description: 'Evaluation timestamp as an RFC3339 or Unix timestamp. Optional.'
- in: query
name: timeout
type: string
required: false
description: 'Evaluation timeout. Defaults to the value of the -query.timeout flag.'
responses:
200:
description: 'Query results in a defined format.'
schema:
$ref: '#/definitions/QueryResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
post:
operationId: 'PostInstantQuery'
summary: 'Evaluates an instant query at a single point in time using POST'
description: |
Submit query data in the request body using URL-encoded form parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Query
consumes:
- application/x-www-form-urlencoded
parameters:
- in: formData
name: query
type: string
required: true
description: 'Prometheus expression query string.'
- in: formData
name: time
type: string
required: false
description: 'Evaluation timestamp as an RFC3339 or Unix timestamp. Optional.'
- in: formData
name: timeout
type: string
required: false
description: 'Evaluation timeout. Defaults to the value of the -query.timeout flag.'
responses:
200:
description: 'Successful query evaluation.'
schema:
$ref: '#/definitions/QueryResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
/v1/metrics/prometheus/api/v1/query_range:
get:
operationId: 'GetRangeQuery'
summary: 'Evaluates an expression query over a range of time'
description: |
Retrieve data over a specified time range by submitting a GET request with query parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Range Query
parameters:
- in: query
name: query
type: string
required: true
description: 'Prometheus expression query string.'
- in: query
name: start
type: string
required: true
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: query
name: end
type: string
required: true
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: query
name: step
type: string
required: true
description: 'Query resolution step width in seconds.'
- in: query
name: timeout
type: string
required: false
description: 'Evaluation timeout. Optional, defaults to the value of the -query.timeout flag.'
responses:
200:
description: 'Range query results in a defined format.'
schema:
$ref: '#/definitions/RangeQueryResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
post:
operationId: 'PostRangeQuery'
summary: 'Evaluates an expression query over a range of time using POST'
description: |
Submit query data in the request body using URL-encoded form parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Range Query
consumes:
- application/x-www-form-urlencoded
parameters:
- in: formData
name: query
type: string
required: true
description: 'Prometheus expression query string.'
- in: formData
name: start
type: string
required: true
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: formData
name: end
type: string
required: true
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: formData
name: step
type: string
required: true
description: 'Query resolution step width in seconds.'
- in: formData
name: timeout
type: string
required: false
description: 'Evaluation timeout. Optional, defaults to the value of the -query.timeout flag.'
responses:
200:
description: 'Successful range query evaluation.'
schema:
$ref: '#/definitions/RangeQueryResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
/v1/metrics/prometheus/api/v1/series:
get:
operationId: 'GetSeriesByLabels'
summary: 'Returns the list of time series that match a certain label set.'
description: |
Retrieve time series data by submitting a GET request with label matchers and time range parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Time Series
parameters:
- in: query
name: 'match[]'
type: 'array'
required: true
items:
type: 'string'
collectionFormat: multi
description: 'Series selector that selects the series to return. At least one must be provided.'
- in: query
name: start
type: 'string'
required: true
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: query
name: end
type: 'string'
required: true
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: query
name: limit
type: 'integer'
required: false
description: 'Maximum number of returned series. Optional.'
responses:
200:
description: 'List of matching time series.'
schema:
$ref: '#/definitions/SeriesResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
post:
operationId: 'PostSeriesByLabels'
summary: 'Returns the list of time series that match a certain label set using POST.'
description: |
Submit label matchers and time range data in the request body using URL-encoded form parameters.
Please ensure to change the region in the URL to match your account's region.
tags:
- Time Series
consumes:
- application/x-www-form-urlencoded
parameters:
- in: formData
name: 'match[]'
type: 'array'
required: true
items:
type: 'string'
collectionFormat: multi
description: 'Series selector that selects the series to return. At least one must be provided.'
- in: formData
name: start
type: 'string'
required: true
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: formData
name: end
type: 'string'
required: true
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp.'
- in: formData
name: limit
type: 'integer'
required: false
description: 'Maximum number of returned series. Optional.'
responses:
200:
description: 'Successful retrieval of matching time series.'
schema:
$ref: '#/definitions/SeriesResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
/v1/metrics/prometheus/api/v1/labels:
get:
operationId: 'GetLabelNames'
summary: 'Returns a list of label names'
description: |
Retrieve a list of all label names optionally filtered by a time range and series selectors.
Please ensure to change the region in the URL to match your account's region.
tags:
- Labels
parameters:
- in: query
name: start
type: 'string'
required: false
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: query
name: end
type: 'string'
required: false
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: query
name: 'match[]'
type: 'array'
required: false
items:
type: 'string'
collectionFormat: multi
description: 'Series selector to narrow down the series from which to read the label names. Optional.'
- in: query
name: limit
type: 'integer'
required: false
description: 'Maximum number of label names to return. Optional.'
responses:
200:
description: 'List of label names.'
schema:
$ref: '#/definitions/LabelNamesResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
post:
operationId: 'PostLabelNames'
summary: 'Returns a list of label names using POST'
description: |
Submit parameters in the request body using URL-encoded form parameters to retrieve a list of label names.
Please ensure to change the region in the URL to match your account's region.
tags:
- Labels
consumes:
- application/x-www-form-urlencoded
parameters:
- in: formData
name: start
type: 'string'
required: false
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: formData
name: end
type: 'string'
required: false
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: formData
name: 'match[]'
type: 'array'
required: false
items:
type: 'string'
collectionFormat: multi
description: 'Series selector to narrow down the series from which to read the label names. Optional.'
- in: formData
name: limit
type: 'integer'
required: false
description: 'Maximum number of label names to return. Optional.'
responses:
200:
description: 'Successful retrieval of label names.'
schema:
$ref: '#/definitions/LabelNamesResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
/v1/metrics/prometheus/api/v1/label/{label_name}/values:
get:
operationId: 'GetLabelValues'
summary: 'Returns a list of label values for a provided label name'
description: |
Retrieves a list of all values associated with a specific label name, optionally filtered by time range and series selectors.
Please ensure to change the region in the URL to match your account's region.
tags:
- Label Values
parameters:
- in: path
name: label_name
type: 'string'
required: true
description: 'The name of the label to retrieve values for.'
- in: query
name: start
type: 'string'
required: false
description: 'Start timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: query
name: end
type: 'string'
required: false
description: 'End timestamp, inclusive, as an RFC3339 or Unix timestamp. Optional.'
- in: query
name: 'match[]'
type: 'array'
required: false
items:
type: 'string'
collectionFormat: multi
description: 'Series selector to narrow down the series from which to read the label values. Optional.'
- in: query
name: limit
type: 'integer'
required: false
description: 'Maximum number of label values to return. Optional.'
responses:
200:
description: 'List of label values.'
schema:
$ref: '#/definitions/LabelValuesResult'
400:
description: 'Invalid request parameters.'
500:
description: 'Internal server error.'
# ::::: Logz.io Dashboards - Dashboards
/perses-public/api/v1/dashboards:
get:
summary: Get all dashboards
description: |
Retrieves a list of all dashboards.
tags:
- Dashboards get all
parameters:
- in: body
type: 'string'
required: false
responses:
'200':
description: List of dashboards
schema:
type: array
items:
type: object
properties:
uid:
type: string
example: dashboard-1
schema:
- name: title
type: string
example: CPU usage
- name: panels
type: string
- name: refresh
type: string
example: 5s
veersion:
type: string
example: 1.0.0
createdAt:
type: string
example: 2024-03-20T10:00:00Z
/perses-public/api/v1/projects/{folderId}/dashboards/{uid}:
get:
summary: Get dashboard by ID
description: |
Retrieves a specific dashboard by its ID.
tags:
- Dashboards get by ID
parameters:
- in: path
name: dashboardId
type: string
required: true
description: The ID of the dashboard to retrieve.
responses:
'200':
description: Dashboard details
schema:
type: object
properties:
uid:
type: string
example: dashboard-1
title:
type: string
example: CPU usage
panels:
type: string
refresh:
type: string
example: 5s
version:
type: string
example: 1.0.0
createdAt:
type: string
example: 2024-03-20T10:00:00Z
/perses-public/api/v1/projects/{folderId}/dashboards:
post:
summary: Create a new dashboard
description: |
Creates a new dashboard in the specified folder.
tags:
- Dashboards create new
parameters:
- in: path
name: folderId
type: string
required: true
description: The ID of the folder where the dashboard will be created.
- in: body
name: body
required: true
schema:
type: object
properties:
title:
type: string
example: CPU usage
panels:
type: string
refresh:
type: string
example: 5s
responses:
'201':
description: Created dashboard details
schema:
type: object
properties:
uid:
type: string
example: dashboard-1
/perses-public/api/v1/projects/{folderId}/dashboards/{uid}/:
put:
summary: Update an existing dashboard
description: |
Updates an existing dashboard in the specified folder.
tags:
- Dashboards update
parameters:
- in: path
name: folderId
type: string
required: true
description: The ID of the folder where the dashboard is located.
- in: path
name: uid
type: string
required: true
description: The ID of the dashboard to update.
- in: body
name: body
required: true
schema:
type: object
properties:
title:
type: string
example: CPU usage updated
panels:
type: string
refresh:
type: string
example: 10s
responses:
'200':
description: Updated dashboard details
schema:
type: object
properties:
uid:
type: string
example: dashboard-1
/perses-public/api/v1/projects/{folderId}/
# --- truncated at 32 KB (457 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logz-io/refs/heads/main/openapi/logz-io-api-openapi.yml