openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Connect to S3 Buckets 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: 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.'
paths:
  /v1/log-shipping/s3-buckets:
    get:
      summary: Retrieve all connected S3 buckets
      description: 'Returns a list of all S3 buckets connected to your Logz.io account.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: getS3Buckets
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/S3BucketResponse'
    post:
      summary: Create a new S3 bucket connector
      description: 'Establishes a new connection of the Logz.io fetcher to an AWS S3 bucket. As a result, logs from your AWS resource will begin shipping to the connected Logz.io account via an AWS S3 bucket.


        Logs will be parsed using the Logz.io custom parsing pipeline for the resource.


        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: createBuckets
      responses:
        default:
          description: successful operation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/S3BucketRequest'
  /v1/log-shipping/s3-buckets/{id}:
    get:
      summary: Retrieve an S3 bucket connector by ID
      description: 'Returns connection details for an S3 bucket connector by its ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: getS3Bucket
      parameters:
      - name: id
        description: Logz.io ID of the S3 Bucket connector. You can run the relevant GET endpoints to retrieve the ID.
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3BucketResponse'
    put:
      summary: Update an S3 bucket connector
      description: 'Updates connection details for an S3 bucket connector.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: updateBucket
      parameters:
      - name: id
        in: path
        description: Logz.io ID of the S3 Bucket connector. You can run the relevant GET endpoints to retrieve the ID.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        default:
          description: successful operation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/S3BucketRequest'
    delete:
      summary: Delete an S3 connector
      description: 'Deletes an S3 bucket connector. As a result, the connected AWS resource will stop shipping logs to your Logz.io account.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: deleteBucket
      parameters:
      - name: id
        description: Logz.io ID of the S3 bucket connector. You can run the relevant GET endpoints to retrieve the ID.
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        default:
          description: successful operation
  /v1/log-shipping/s3-buckets/aws-assume-role-details:
    get:
      summary: Get account information for IAM Role
      description: 'Returns the Logz.io parameters needed to create an AWS IAM Role in the AWS admin console.


        The next steps after running this endpoint:

        * Open your AWS admin console and create a new IAM Role. Once the role is created, you will obtain an ARN for it. Keep it handy for the next step.

        * Create a new S3 bucket connector. Provide the ARN from the previous step in the request body.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Connect to S3 Buckets
      operationId: getAWSAssumeRoleDetails
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AWSAssumeRoleDetails'
components:
  schemas:
    S3BucketResponse:
      type: object
      required:
      - bucket
      - region
      - logsType
      properties:
        accessKey:
          type: string
          description: AWS S3 bucket access key
          example: ee07df5801500745419c6dff
        secretKey:
          type: string
          description: AWS S3 bucket secret key
          example: 506d891fe2163a511b450eddc3279539f6
        arn:
          type: string
          description: Amazon Resource Name (ARN) to uniquely identify the S3 bucket. To generate a new ARN, create a new IAM Role in your AWS admin console.
        bucket:
          type: string
          description: AWS S3 bucket name
          example: AWS bucket
        prefix:
          type: string
          description: Prefix of the AWS S3 bucket
          example: AWSLogs/7364988021587/myprefix
        active:
          type: boolean
          default: true
          description: If `true`, the S3 bucket connector is active and logs are being fetched to Logz.io. If `false`, the connector is disabled.
          example: true
        addS3ObjectKeyAsLogField:
          type: boolean
          default: false
          description: If `true`, enriches logs with a new field detailing the S3 object key.
          example: true
        region:
          type: string
          description: Specify one supported AWS region.
          enum:
          - US_EAST_1
          - US_EAST_2
          - US_WEST_1
          - US_WEST_2
          - EU_WEST_1
          - EU_WEST_2
          - EU_WEST_3
          - EU_CENTRAL_1
          - AP_NORTHEAST_1
          - AP_NORTHEAST_2
          - AP_SOUTHEAST_1
          - AP_SOUTHEAST_2
          - SA_EAST_1
          - AP_SOUTH_1
          - CA_CENTRAL_1
        logsType:
          type: string
          enum:
          - elb
          - vpcflow
          - S3Access
          - cloudfront
          description: Specifies the log type being sent to Logz.io. Determines the parsing pipeline used to parse and map the logs. [Learn more about parsing options supported by Logz.io](/user-guide/log-shipping/built-in-log-types.html).
          example: elb
    S3BucketRequest:
      type: object
      required:
      - bucket
      - region
      - logsType
      properties:
        accessKey:
          type: string
          description: AWS S3 bucket access key
          example: ee07df5801500745419c6dff
        secretKey:
          type: string
          description: AWS S3 bucket secret key
          example: 506d891fe2163a511b450eddc3279539f6
        arn:
          type: string
          description: Amazon Resource Name (ARN) to uniquely identify the S3 bucket. To generate a new ARN, create a new IAM Role in your AWS admin console.
        bucket:
          type: string
          description: AWS S3 bucket name
          example: AWS bucket
        prefix:
          type: string
          description: Prefix of the AWS S3 bucket
          example: AWSLogs/7364988021587/myprefix
        active:
          type: boolean
          default: true
          description: If `true`, the S3 bucket connector is active and logs are being shipped to Logz.io. If `false`, the connector is disabled.
          example: true
        addS3ObjectKeyAsLogField:
          type: boolean
          default: false
          description: If `true`, enriches logs with a new field detailing the S3 object key.
          example: true
        region:
          type: string
          description: Specify one supported AWS region.
          enum:
          - US_EAST_1
          - US_EAST_2
          - US_WEST_1
          - US_WEST_2
          - EU_WEST_1
          - EU_WEST_2
          - EU_WEST_3
          - EU_CENTRAL_1
          - AP_NORTHEAST_1
          - AP_NORTHEAST_2
          - AP_SOUTHEAST_1
          - AP_SOUTHEAST_2
          - SA_EAST_1
          - AP_SOUTH_1
          - CA_CENTRAL_1
        logsType:
          type: string
          enum:
          - elb
          - vpcflow
          - S3Access
          - cloudfront
          description: Specify the log type you will be sending to Logz.io. As a result, Logz.io will apply the appropriate parsing pipeline. [Learn more about parsing options supported by Logz.io](/user-guide/log-shipping/built-in-log-types.html).
          example: elb
    AWSAssumeRoleDetails:
      type: object
      properties:
        logzioAWSAccountId:
          type: string
          description: Logz.io account ID. Provide this account ID when creating a new AWS IAM Role.
          example: null
        assignedExternalId:
          type: string
          description: Logz.io external ID. Provide this external ID when creating a new AWS IAM Role.
          example: null
  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.