openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Grafana Folders 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 Folders
paths:
  /v1/grafana/api/folders:
    get:
      summary: Get all folders
      operationId: getAllFolders
      description: 'Returns all folders the authenticated user can view.

        Make sure the region in the URL matches your account''s region.'
      tags:
      - Grafana Folders
      parameters:
      - name: limit
        in: query
        description: Maximum number of folders to return (default 1000)
        schema:
          type: integer
      - name: page
        in: query
        description: Page number (starts at 1)
        schema:
          type: integer
      - name: parentUid
        in: query
        description: Parent folder UID to fetch subfolders
        schema:
          type: string
      responses:
        '200':
          description: List of folders
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    uid:
                      type: string
                    title:
                      type: string
    post:
      summary: Create a new Grafana folder
      operationId: createNewGrafanaFolder
      description: 'Creates a new folder.

        Make sure the region in the URL matches your account''s region.'
      tags:
      - Grafana Folders
      responses:
        '200':
          description: Folder created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  uid:
                    type: string
                  title:
                    type: string
                  url:
                    type: string
                  created:
                    type: string
                    format: date-time
                  updated:
                    type: string
                    format: date-time
                  version:
                    type: integer
                    format: int64
                additionalProperties: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                  example: My New Folder
                uid:
                  type: string
                overwrite:
                  type: boolean
                  example: false
        required: true
  /v1/grafana/api/folders/{uid}:
    parameters:
    - in: path
      name: uid
      required: true
      description: The UID of the folder
      schema:
        type: string
    get:
      summary: Get Grafana folder by UID
      operationId: getGrafanaFolderByUid
      tags:
      - Grafana Folders
      description: 'Returns a single folder by UID.

        Make sure the region in the URL matches your account''s region.'
      responses:
        '200':
          description: Folder details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  uid:
                    type: string
                  title:
                    type: string
                  url:
                    type: string
                  created:
                    type: string
                    format: date-time
                  updated:
                    type: string
                    format: date-time
                  createdBy:
                    type: string
                  updatedBy:
                    type: string
                  version:
                    type: integer
                    format: int64
    put:
      summary: Update a Grafana folder by UID
      operationId: updateGrafanaFolderByUid
      tags:
      - Grafana Folders
      description: 'Updates a folder by UID.

        Make sure the region in the URL matches your account''s region.'
      responses:
        '200':
          description: Folder updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The numeric ID of the folder
                    example: 123
                  uid:
                    type: string
                    description: The UID of the folder
                    example: my-folder-uid
                  title:
                    type: string
                    description: The title of the folder
                    example: Updated Folder Title
                  url:
                    type: string
                    description: The URL path to the folder
                    example: /dashboards/f/my-folder-uid/updated-folder-title
                  created:
                    type: string
                    format: date-time
                    description: ISO timestamp when the folder was created
                    example: '2024-01-15T10:30:00Z'
                  updated:
                    type: string
                    format: date-time
                    description: ISO timestamp when the folder was last updated
                    example: '2024-01-16T14:45:30Z'
                  version:
                    type: integer
                    description: The version number of the folder
                    example: 2
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                uid:
                  type: string
                  description: The UID of the folder
                  example: my-folder-uid
                title:
                  type: string
                  description: The title of the folder
                  example: Updated Folder Title
                overwrite:
                  type: boolean
                  description: Whether to overwrite if folder exists
                  example: false
        required: true
    delete:
      summary: Delete a Grafana folder by UID
      operationId: deleteGrafanaFolderByUid
      tags:
      - Grafana Folders
      description: 'Deletes a folder by UID.

        Make sure the region in the URL matches your account''s region.'
      responses:
        '204':
          description: Folder deleted
        '404':
          description: Folder not Found
        '400':
          description: Folder is not empty
          messageId:
            type: string
            example: folder.not-empty
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: null
                  type: string
                example: 'Folder cannot be deleted: folder is not empty'
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.