openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Manage log shipping tokens 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: Manage log shipping tokens
  description: Use these API endpoints to create, update, retrieve, or delete log shipping tokens.
paths:
  /v1/log-shipping/tokens:
    post:
      tags:
      - Manage log shipping tokens
      summary: Create a log shipping token
      description: 'Creates a log shipping token for this account.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: createNewLogShippingToken
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTokensModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingTokensRequest'
  /v1/log-shipping/tokens/{id}:
    get:
      tags:
      - Manage log shipping tokens
      summary: Retrieve a log shipping token by ID
      description: 'Returns details for the specified shipping token.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: getLogShippingTokenById
      parameters:
      - name: id
        in: path
        required: true
        description: This token's ID.
        example: 786351
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTokensModel'
    put:
      tags:
      - Manage log shipping tokens
      summary: Update a log shipping token
      description: 'Enables/disables a log shipping token and/or renames it.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: updateLogShippingToken
      parameters:
      - name: id
        in: path
        required: true
        description: This token's ID.
        example: 786351
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTokensModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingTokensRequest'
    delete:
      tags:
      - Manage log shipping tokens
      summary: Delete a log shipping token
      description: 'Deletes a log shipping token by its ID, while providing relevant information about the token''s recent status and activity.


        An account must have at least 1 enabled token. You won''t be able to disable or delete the last token.

        **Important**: Active tokens can be deleted using this call. Confirm that a token is no longer needed before deleting it.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: deleteLogShippingToken
      parameters:
      - name: id
        in: path
        required: true
        description: This token's ID.
        example: 786351
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTokensModel'
  /v1/log-shipping/tokens/limits:
    get:
      tags:
      - Manage log shipping tokens
      summary: Get number of available tokens
      description: Returns the number of log shipping tokens currently in use and the number of available tokens that can be enabled. Disabled tokens don't count against the token limit. Please ensure to change the region in the URL to match your account's region.
      operationId: getLogShippingTokensLimits
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTokensLimitsResponse'
  /v1/log-shipping/tokens/search:
    post:
      tags:
      - Manage log shipping tokens
      summary: Retrieve log shipping tokens
      description: 'Returns the relevant shipping tokens, filtered, sorted and paginated as per the request.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: searchLogShippingTokens
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSearchResponseShippingTokensModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingTokensSearchRequest'
components:
  schemas:
    ShippingTokensLimitsResponse:
      type: object
      properties:
        maxAllowedTokens:
          type: integer
          format: int32
          description: The number of log shipping tokens this account can have.
          example: 50
        numOfEnabledTokens:
          type: integer
          format: int32
          description: The number of log shipping tokens currently enabled for this account.
          example: 27
    ShippingTokensSortRequest:
      type: object
      properties:
        field:
          type: string
          enum:
          - createdAt
          - name
          description: To sort by creation date, use `"createdAt"`. To sort by name, use `"name"`.
          example: name
        descending:
          type: boolean
          description: For descending order, use `true`. For ascending order, use `false`.
    ShippingTokensSearchRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/ShippingTokensFilterRequest'
        sort:
          type: array
          description: Sorts the results before returning them.
          items:
            $ref: '#/components/schemas/ShippingTokensSortRequest'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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
    ShippingTokensFilterRequest:
      type: object
      required:
      - enabled
      description: Filters your search for token attributes.
      properties:
        enabled:
          type: boolean
          description: Set to `true` to filter for enabled tokens. Set to `false` to filter for disabled tokens.
    PagedSearchResponseShippingTokensModel:
      type: object
      properties:
        total:
          type: integer
          format: int32
        results:
          type: array
          items:
            $ref: '#/components/schemas/ShippingTokensModel'
        pagination:
          $ref: '#/components/schemas/Pagination'
    ShippingTokensRequest:
      type: object
      properties:
        name:
          type: string
          description: Descriptive name for this token.
          example: staging eu
        enabled:
          type: boolean
          default: true
          description: To enable this token, `true`. To disable, `false`.
    ShippingTokensModel:
      type: object
      properties:
        name:
          type: string
          description: This token's name.
          example: apac prod
        id:
          type: integer
          format: int32
          description: This token's ID.
          example: 786351
        token:
          type: string
          description: The token itself.
          example: 6bLXmMA6FLibc7ySSqNcCfvbhtqT0rPS
        updatedAt:
          type: string
          description: Unix timestamp of when this token was last updated.
          example: 414720000
        updatedBy:
          type: string
          description: Email address of the last user to update this token.
          example: shalom.the.mighty@gmail.com
        createdAt:
          type: string
          description: Unix timestamp of when this token was created.
          example: 389836800
        createdBy:
          type: string
          description: Email address of the user who created this token.
          example: you.got.this@gmail.com
        enabled:
          type: boolean
          description: If this token is enabled, `true`. If it's disabled, `false`.
  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.