openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Lookup lists 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: Lookup lists
paths:
  /v1/lookup-lists:
    post:
      summary: Create lookup list
      description: 'Creates a new lookup list. After you create the list, you can run the endpoint to add elements to the list.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: createLookupList
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupList'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupListCreateRequest'
  /v1/lookup-lists/search:
    post:
      summary: Get all/Search lookup lists
      description: 'Searches for lookup lists by name or ID. Can also be run without a filter to return the full list of existing lookups. Returns a paginated list of results.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: searchLookupLists
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSearchResponseLookupList'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupListsSearchRequest'
  /v1/lookup-lists/{id}:
    get:
      summary: Get lookup by ID
      description: 'Retrieves the general details for an existing lookup list.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: getLookupList
      parameters:
      - name: id
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupList'
    put:
      summary: Update lookup list
      description: 'Update the name and/or description of an exisiting lookup list.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: updateLookupList
      parameters:
      - name: id
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupList'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupList'
        required: true
    delete:
      summary: Delete lookup list
      description: 'Deletes a lookup list. Note that this action can affect rules, dashboards, and reports if they are dependent on the lookup list.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: deleteLookupList
      parameters:
      - name: id
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupList'
  /v1/lookup-lists/{lookupListId}/elements:
    post:
      summary: Add element to a lookup list
      description: 'Adds a new element to an existing lookup list. An element is a field value and comment (helpful description that does not affect the lookup functionally).

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: createLookupListElement
      parameters:
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupListElement'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupListElementCreateRequest'
        required: true
  /v1/lookup-lists/{lookupListId}/elements/search:
    post:
      summary: Get all/Search lookup elements
      description: 'Searches elements in a specified lookup list. Can also be run without a filter to return the full list of elements. Returns a paginated list of results.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: searchLookupListElements
      parameters:
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSearchResponseLookupListElement'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupListElementsSearchRequest'
  /v1/lookup-lists/{lookupListId}/elements/{id}:
    get:
      summary: Get element
      description: 'Retrieves a specific lookup element by its ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: getLookupListElement
      parameters:
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: ID of a specific value element contained in the lookup list.
        example: 20
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupListElement'
    put:
      summary: Update element
      description: 'Changes the value and/or comment of a specific element, identified by its ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: updateLookupListElement
      parameters:
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: ID of a specific value element contained in the lookup list.
        example: 20
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupListElement'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupListElement'
        required: true
    delete:
      summary: Delete element
      description: 'Deletes a specific lookup element, identified by its ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Lookup lists
      operationId: deleteLookupListElement
      parameters:
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: ID of a specific value element contained in the lookup list.
        example: 20
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupListElement'
  /v1/lookup-lists/{lookupListId}/elements/bulk-add:
    post:
      tags:
      - Lookup lists
      operationId: addLookupListElements
      summary: Add elements in bulk
      description: 'Adds an array of elements to an existing Lookup list and sets the expiration date for the lookup.

        Please ensure to change the region in the URL to match your account''s region.'
      parameters:
      - name: defaultTTL
        in: query
        required: false
        description: Optional. The expiration date and time of the lookup list as UNIX epoch milliseconds. When this parameter is left empty, the lookup list does not expire.
        schema:
          type: integer
          format: int64
      - name: lookupListId
        in: path
        required: true
        description: GUID of the lookup list.
        example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupListElementBulkResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/LookupListElementCreateRequest'
        required: true
components:
  schemas:
    PagedSearchResponseLookupListElement:
      type: object
      properties:
        total:
          type: integer
          format: int32
          description: Total number of search results. The results are relvent elements contained in the lookup list.
        results:
          type: array
          items:
            $ref: '#/components/schemas/LookupListElement'
        pagination:
          $ref: '#/components/schemas/Pagination'
    LookupListElementBulkResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - SUCCESS
          - PARTIAL_FAILED
          - FAILED
          description: Returns the status of the request.
          example: SUCCESS
        numOfAddedElements:
          type: integer
          format: int32
          description: Total number of new elements added to the Lookup list.
          example: 32
        numOfMergedElements:
          type: integer
          format: int32
          description: Total number of elements merged with duplicate values in the existing list. (In other words, the number of existing elements that were updated by the request.)
          example: 42
    LookupListElement:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: ID of the element in the Lookup list.
        value:
          type: string
          minLength: 1
          maxLength: 80
          description: A single field value. You should ensure that the lookup list contains a list of values all mapped to the same field.
          example: 54.53.1.1
        comment:
          type: string
          description: Optional. A place to add a note or additional details about the value. For example, if the value is an IP address, the comment can identify the server.
          maxLength: 200
          example: ABC Server
        expirationDate:
          type: integer
          format: int64
          description: Optional. The expiration date and time of the lookup list as UNIX epoch milliseconds. When this parameter is left empty, the lookup list does not expire.
    Pagination:
      type: object
      description: Default pagination is a page of 25 results. Look for the `total` field in the response for the number of available results overall, and use the pagination function to page through the results.
      properties:
        pageNumber:
          type: integer
          format: int32
          description: If you overshoot the page number, it will return empty with no results, but it won't fail the request.
          default: 1
          example: 1
        pageSize:
          type: integer
          format: int32
          description: Controls the number of results per page. Valid inputs are 1 to 1000.
          maximum: 1000
          default: 25
          example: 100
    LookupList:
      type: object
      summary: General indentifiers for the lookup - its ID, name, and description.
      properties:
        id:
          type: string
          description: GUID of the lookup list.
          example: 7c985e09-3db6-5dc6-ae33-58403493e13f
        name:
          type: string
          minLength: 1
          maxLength: 40
          description: Name of the lookup list.
        description:
          type: string
          minLength: 0
          maxLength: 400
          description: Description of the lookup list.
    LookupListElementsFilter:
      type: object
      description: Filter for elements by value, element ID, or by comments that contain a search term. If multiple properties are sent, they must all be satisfied (`AND` logic).
      properties:
        searchTerm:
          type: string
          description: Filters for values or comments that contain the search term.
          example: server
        byIds:
          type: array
          description: Filters by element IDs.
          items:
            type: integer
            format: int32
        byValues:
          type: array
          description: Filters by exact value. (Looks for elements that match any one of the values in the array.)
          items:
            type: string
    LookupListElementCreateRequest:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          minLength: 1
          maxLength: 80
          description: A single field value.
          example: 54.53.1.1
        comment:
          type: string
          minLength: 0
          maxLength: 200
          description: Optional. A place to add a note or additional details about the value. For example, if the value is an IP address, the comment can identify the server.
          example: ABC Server
        expirationDate:
          type: integer
          format: int64
          description: Optional. The expiration date and time of the lookup list as UNIX epoch milliseconds. When this parameter is left empty, the lookup list does not expire.
    LookupListsSearchRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/LookupListsFilter'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PagedSearchResponseLookupList:
      type: object
      properties:
        total:
          type: integer
          format: int32
          description: Total number of search results.
        results:
          type: array
          items:
            $ref: '#/components/schemas/LookupList'
        pagination:
          $ref: '#/components/schemas/Pagination'
    LookupListsFilter:
      type: object
      description: Filter by names that contain a term, by lookup ID, or by both. If both properties are sent, they must both be satsified (`AND` logic).
      properties:
        searchTerm:
          type: string
          description: Filters for lookup names that contains the search term.
          example: servers
        byIds:
          type: array
          description: List of lookup IDs.
          items:
            type: string
    LookupListElementsSearchRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/LookupListElementsFilter'
        pagination:
          $ref: '#/components/schemas/Pagination'
    LookupListCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 0
          maxLength: 40
          description: Name of the lookup list. If null, the list will be named `Untitled` followed by the running number.
          default: Untitled##
        description:
          type: string
          minLength: 0
          maxLength: 400
          description: A place to add a free text description of the lookup list's purpose, uses and dependencies.
  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.