openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Grafana annotations API
  termsOfService: https://logz.io/about-us/terms-of-use/
  contact:
    email: help@logz.io
    url: https://docs.logz.io/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.logz.io/
security:
- X-API-TOKEN: []
tags:
- name: Grafana annotations
paths:
  /v1/grafana/api/v1/provisioning/alert-rules/<<UID>>:
    delete:
      operationId: deleteAlertRulesByUID
      summary: Delete alert rule by UID
      description: 'Deletes the annotation that matches the specified id.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: path
        name: UID
        schema:
          description: Alert rule UID.
        required: true
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message.
                    example: Annotation deleted
  /v1/grafana/api/annotations/:
    get:
      operationId: getAnnotations
      summary: Find annotations
      description: 'Searches for annotations in the Grafana database.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: query
        name: from
        schema:
          description: Epoch datetime in milliseconds. Optional.
      - in: query
        name: to
        schema:
          description: Epoch datetime in milliseconds. Optional.
      - in: query
        name: limit
        schema:
          description: Optional - default is 100. Max limit for results returned.
      - in: query
        name: alertId
        schema:
          description: Optional. Find annotations for a specified alert.
      - in: query
        name: dashboardId
        schema:
          description: Optional. Find annotations that are scoped to a specific dashboard
      - in: query
        name: panelId
        schema:
          description: Optional. Find annotations that are scoped to a specific panel
      - in: query
        name: userId
        schema:
          description: Optional. Find annotations created by a specific user
      - in: query
        name: type
        schema:
          description: Optional. Return alerts or user created annotations
      - in: query
        name: tags
        schema:
          description: 'Optional. Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times e.g. tags=tag1&tags=tag2.         '
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID.
                    example: 1
                  dashboardId:
                    type: integer
                    description: Dashboard ID.
                    example: 1
                  dashboardUId:
                    type: string
                    description: Dashboard UID.
                    example: ABcdEFghij
                  dashboardSlug:
                    type: string
                    description: Dashboard slug.
                    example: sensors
                  panelId:
                    type: integer
                    description: Panel ID.
                    example: 1
                  name:
                    type: string
                    description: Dashboard name.
                    example: fire place sensor
                  state:
                    type: string
                    description: Dashboard state.
                    example: alerting
                  newStateDate:
                    type: string
                    description: Date of the new state.
                    example: '2018-05-14T05:55:20+02:00'
                  evalDate:
                    type: string
                    description: Evaluation date.
                    example: '0001-01-01T00:00:00Z'
                  evalData:
                    type: array
                    description: Evaluation data.
                    items:
                      type: string
                  executionError:
                    type: string
                    description: Execution error, if present
                    example: ''
                  url:
                    type: string
                    description: Dashboard url.
                    example: http://grafana.com/dashboard/db/sensors
    post:
      operationId: createAnnotations
      summary: Create annotations
      description: 'Creates an annotation in the Grafana database.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID.
                    example: 1
                  message:
                    type: string
                    description: Confirmation message.
                    example: Annotation added
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dashboardId:
                  type: integer
                  description: Id of the dashboard. The dashboardId and panelId fields are optional. If they are not specified then a global annotation is created and can be queried in any dashboard that adds the Grafana annotations data source.
                panelId:
                  type: integer
                  description: Id of the panel. The dashboardId and panelId fields are optional. If they are not specified then a global annotation is created and can be queried in any dashboard that adds the Grafana annotations data source.
                time:
                  type: integer
                  description: Epoch time in milliseconds.
                timeEnd:
                  type: integer
                  description: Epoch time in milliseconds.
                tags:
                  type: array
                  description: Annotation tags.
                  items:
                    type: string
                    example: tag1
                text:
                  type: string
                  description: Annotation Description.
  /v1/grafana/api/annotations/graphite:
    post:
      operationId: createAnnotationsGraphite
      summary: Create annotations in Graphite format
      description: 'Creates an annotation in the Grafana database by using Graphite-compatible event format.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID.
                    example: 1
                  message:
                    type: string
                    description: Confirmation message.
                    example: Graphite annotation added
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                what:
                  type: string
                  description: Graphite annotation.
                  example: Event - deploy
                when:
                  type: integer
                  description: Epoch datetime of the annotation in milliseconds. Optional. If `when` is not specified then the current time will be used as annotation’s timestamp..
                tags:
                  type: array
                  description: Annotation tags.  Can also be in prior to Graphite 0.10.0 format (string with multiple tags being separated by a space).
                  example:
                  - deploy
                  - production
                  items:
                    type: string
                data:
                  type: string
                  description: Annotation Description.
                  example: deploy of master branch happened at Wed Jul 6 22:34:41 UTC 2016
  /v1/grafana/api/annotations/:id:
    put:
      operationId: updateAnnotations
      summary: Update annotations
      description: 'Updates an annotation in the Grafana database.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: path
        name: id
        schema:
          description: Id of the annotation.
        required: true
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message.
                    example: Annotation updated
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time:
                  type: integer
                  description: Epoch time in milliseconds.
                timeEnd:
                  type: integer
                  description: Epoch time in milliseconds.
                  example: Event - deploy
                text:
                  type: string
                  description: Annotation Description.
                tags:
                  type: attay
                  description: Tags.
                  example:
                  - tag3
                  - tag4
                  - tag5
                  items:
                    type: string
    patch:
      operationId: patchAnnotations
      summary: Patch annotations
      description: 'Updates one or more properties of an annotation that matches the specified id. This operation currently supports updating of the text, tags, time and timeEnd properties.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: path
        name: id
        schema:
          description: Id of the annotation.
        required: true
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message.
                    example: Annotation patched
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Annotation Description.
                tags:
                  type: attay
                  description: Tags.
                  items:
                    type: string
    delete:
      operationId: deleteAnnotations
      summary: Delete annotation by id
      description: 'Deletes the annotation that matches the specified id.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: path
        name: id
        schema:
          description: Id of the annotation.
        required: true
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message.
                    example: Annotation deleted
  /v1/grafana/api/annotations/tags:
    get:
      operationId: getAnnotationsTags
      summary: Get event tags created in annotations
      description: 'Searches for event tags in annotations in the Grafana database.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Grafana annotations
      parameters:
      - in: query
        name: tag
        schema:
          description: Tag. Optional.
      - in: query
        name: limit
        schema:
          description: Optional. A number, where the default is 100. Max limit for results returned.
      responses:
        200:
          description: successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    description: Query result.
                    properties:
                      tags:
                        type: object
                        description: Tags retrieved by the query.
                        properties:
                          tag:
                            type: string
                            description: Tag.
                            example: outage
                          count:
                            type: integer
                            description: Tags count.
                            example: 1
components:
  securitySchemes:
    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
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)
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.