APIs.io Engineering Platform Magic PCAP Collection API

openapi: 3.2.0
info:
  description: 'To get started using Cloudflare''s products and services via the API, refer to [how to interact with Cloudflare](https://developers.cloudflare.com/fundamentals/basic-tasks/interact-with-cloudflare/), which covers using tools like [Terraform](https://developers.cloudflare.com/terraform/#cloudflare-terraform) and the [official SDKs](https://developers.cloudflare.com/fundamentals/api/reference/sdks/) to maintain your Cloudflare resources.


    Using the Cloudflare API requires authentication so that Cloudflare knows who is making requests and what permissions you have. Create an API token to grant access to the API to perform actions.


    To create an API token, from the Cloudflare dashboard, go to My Profile > API Tokens and select Create Token. For more information on how to create and troubleshoot API tokens, refer to

    our [API fundamentals](https://developers.cloudflare.com/fundamentals/api/).


    Totally new to Cloudflare? [Start here](https://developers.cloudflare.com/fundamentals/get-started/).'
  license:
    name: BSD-3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
  title: APIs.io Engineering Platform Cloudflare Magic PCAP Collection API
  version: 4.0.0
tags:
- name: Magic PCAP Collection
paths:
  /accounts/{account_id}/pcaps:
    get:
      description: Lists all packet capture requests for an account.
      operationId: magic-pcap-collection-list-packet-capture-requests
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_collection_response'
          description: List packet capture requests response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_collection_response'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: List packet capture requests response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform List packet capture requests
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      - Magic Firewall Packet Captures - Read PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
    post:
      description: Create new PCAP request for account.
      operationId: magic-pcap-collection-create-pcap-request
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/magic-visibility_pcaps_request_pcap'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_single_response'
          description: Create PCAP request response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_single_response'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: Create PCAP request response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Create PCAP request
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
  /accounts/{account_id}/pcaps/{pcap_id}:
    get:
      description: Get information for a PCAP request by id.
      operationId: magic-pcap-collection-get-pcap-request
      parameters:
      - in: path
        name: pcap_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_single_response'
          description: Get PCAP request response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_single_response'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: Get PCAP request response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Get PCAP request
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      - Magic Firewall Packet Captures - Read PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
  /accounts/{account_id}/pcaps/{pcap_id}/download:
    get:
      description: Download PCAP information into a file. Response is a binary PCAP file.
      operationId: magic-pcap-collection-download-simple-pcap
      parameters:
      - in: path
        name: pcap_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      responses:
        '200':
          content:
            application/vnd.tcpdump.pcap: {}
          description: Download Simple PCAP response
        default:
          content:
            application/json: {}
          description: Download Simple PCAP response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Download Simple PCAP
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      - Magic Firewall Packet Captures - Read PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
  /accounts/{account_id}/pcaps/ownership:
    get:
      description: List all buckets configured for use with PCAPs API.
      operationId: magic-pcap-collection-list-pca-ps-bucket-ownership
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_ownership_collection'
          description: List PCAPs Bucket Ownership response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_ownership_collection'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: List PCAPs Bucket Ownership response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform List PCAPs Bucket Ownership
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      - Magic Firewall Packet Captures - Read PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
    post:
      description: Adds an AWS or GCP bucket to use with full packet captures.
      operationId: magic-pcap-collection-add-buckets-for-full-packet-captures
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/magic-visibility_pcaps_ownership_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_ownership_single_response'
          description: Add buckets for full packet captures response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_ownership_single_response'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: Add buckets for full packet captures response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Add buckets for full packet captures
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
  /accounts/{account_id}/pcaps/ownership/{ownership_id}:
    delete:
      description: Deletes buckets added to the packet captures API.
      operationId: magic-pcap-collection-delete-buckets-for-full-packet-captures
      parameters:
      - in: path
        name: ownership_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      responses:
        '204':
          description: Delete buckets for full packet captures response
        default:
          content:
            application/json: {}
          description: Delete buckets for full packet captures response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Delete buckets for full packet captures
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
  /accounts/{account_id}/pcaps/ownership/validate:
    post:
      description: Validates buckets added to the packet captures API.
      operationId: magic-pcap-collection-validate-buckets-for-full-packet-captures
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/magic-visibility_identifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/magic-visibility_pcaps_ownership_validate_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/magic-visibility_pcaps_ownership_single_response'
          description: Validate buckets for full packet captures response
        default:
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/magic-visibility_pcaps_ownership_single_response'
                - $ref: '#/components/schemas/magic-visibility_api-response-common-failure'
          description: Validate buckets for full packet captures response failure
      security:
      - api_email: []
        api_key: []
      summary: APIs.io Engineering Platform Validate buckets for full packet captures
      tags:
      - Magic PCAP Collection
      x-api-token-group:
      - Magic Firewall Packet Captures - Write PCAPs API
      x-cfPlanAvailability:
        business: false
        enterprise: true
        free: false
        pro: false
components:
  schemas:
    magic-visibility_pcaps_ownership_collection:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-collection'
      - properties:
          result:
            items:
              $ref: '#/components/schemas/magic-visibility_pcaps_ownership_response'
            type:
            - array
            - 'null'
    magic-visibility_pcaps_collection_response:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-collection'
      - properties:
          result:
            items:
              anyOf:
              - $ref: '#/components/schemas/magic-visibility_pcaps_response_simple'
              - $ref: '#/components/schemas/magic-visibility_pcaps_response_full'
            type: array
    magic-visibility_pcaps_response_simple:
      properties:
        filter_v1:
          $ref: '#/components/schemas/magic-visibility_pcaps_filter_v1'
        id:
          $ref: '#/components/schemas/magic-visibility_pcaps_id'
        status:
          $ref: '#/components/schemas/magic-visibility_pcaps_status'
        submitted:
          $ref: '#/components/schemas/magic-visibility_pcaps_submitted'
        system:
          $ref: '#/components/schemas/magic-visibility_pcaps_system'
        time_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_time_limit'
        type:
          $ref: '#/components/schemas/magic-visibility_pcaps_type'
      type: object
    magic-visibility_pcaps_byte_limit:
      description: The maximum number of bytes to capture. This field only applies to `full` packet captures.
      example: 500000
      maximum: 1e+09
      minimum: 1
      type: number
    magic-visibility_identifier:
      description: Identifier
      example: 023e105f4ecef8ad9ca31a8372d0c353
      maxLength: 32
      readOnly: true
      type: string
    magic-visibility_pcaps_ownership_request:
      properties:
        destination_conf:
          $ref: '#/components/schemas/magic-visibility_pcaps_destination_conf'
      required:
      - destination_conf
      type: object
    magic-visibility_pcaps_ownership_challenge:
      description: The ownership challenge filename stored in the bucket.
      example: ownership-challenge-9883874ecac311ec8475433579a6bf5f.txt
      type: string
    magic-visibility_pcaps_request_pcap:
      anyOf:
      - $ref: '#/components/schemas/magic-visibility_pcaps_request_simple'
      - $ref: '#/components/schemas/magic-visibility_pcaps_request_full'
    magic-visibility_pcaps_status:
      description: The status of the packet capture request.
      enum:
      - unknown
      - success
      - pending
      - running
      - conversion_pending
      - conversion_running
      - complete
      - failed
      example: success
      type: string
    magic-visibility_messages:
      example: []
      items:
        properties:
          code:
            minimum: 1000
            type: integer
          message:
            type: string
        required:
        - code
        - message
        type: object
        uniqueItems: true
      type: array
    magic-visibility_pcaps_ownership_validate_request:
      properties:
        destination_conf:
          $ref: '#/components/schemas/magic-visibility_pcaps_destination_conf'
        ownership_challenge:
          $ref: '#/components/schemas/magic-visibility_pcaps_ownership_challenge'
      required:
      - destination_conf
      - ownership_challenge
      type: object
    magic-visibility_pcaps_destination_conf:
      description: The full URI for the bucket. This field only applies to `full` packet captures.
      example: s3://pcaps-bucket?region=us-east-1
      type: string
    magic-visibility_pcaps_request_simple:
      properties:
        filter_v1:
          $ref: '#/components/schemas/magic-visibility_pcaps_filter_v1'
        packet_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_packet_limit'
        system:
          $ref: '#/components/schemas/magic-visibility_pcaps_system'
        time_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_time_limit'
        type:
          $ref: '#/components/schemas/magic-visibility_pcaps_type'
      required:
      - time_limit
      - packet_limit
      - type
      - system
      type: object
    magic-visibility_api-response-collection:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-common'
      - properties:
          result:
            items: {}
            type:
            - array
            - 'null'
          result_info:
            $ref: '#/components/schemas/magic-visibility_result_info'
      type: object
    magic-visibility_pcaps_error_message:
      description: An error message that describes why the packet capture failed. This field only applies to `full` packet captures.
      example: No packets matched the filter in the time limit given. Please modify the filter or try again.
      type: string
    magic-visibility_pcaps_time_limit:
      description: The packet capture duration in seconds.
      example: 300
      maximum: 300
      minimum: 1
      type: number
    magic-visibility_result_info:
      properties:
        count:
          description: Total number of results for the requested service
          example: 1
          type: number
        page:
          description: Current page within paginated list of results
          example: 1
          type: number
        per_page:
          description: Number of results per page of results
          example: 20
          type: number
        total_count:
          description: Total results available without any search parameters
          example: 2000
          type: number
      type: object
    magic-visibility_pcaps_type:
      description: The type of packet capture. `Simple` captures sampled packets, and `full` captures entire payloads and non-sampled packets.
      enum:
      - simple
      - full
      example: simple
      type: string
    magic-visibility_pcaps_response_full:
      properties:
        byte_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_byte_limit'
        colo_name:
          $ref: '#/components/schemas/magic-visibility_pcaps_colo_name'
        destination_conf:
          $ref: '#/components/schemas/magic-visibility_pcaps_destination_conf'
        error_message:
          $ref: '#/components/schemas/magic-visibility_pcaps_error_message'
        filter_v1:
          $ref: '#/components/schemas/magic-visibility_pcaps_filter_v1'
        id:
          $ref: '#/components/schemas/magic-visibility_pcaps_id'
        status:
          $ref: '#/components/schemas/magic-visibility_pcaps_status'
        submitted:
          $ref: '#/components/schemas/magic-visibility_pcaps_submitted'
        system:
          $ref: '#/components/schemas/magic-visibility_pcaps_system'
        time_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_time_limit'
        type:
          $ref: '#/components/schemas/magic-visibility_pcaps_type'
      type: object
    magic-visibility_api-response-common-failure:
      properties:
        errors:
          allOf:
          - $ref: '#/components/schemas/magic-visibility_messages'
          example:
          - code: 7003
            message: No route for the URI
          minLength: 1
        messages:
          allOf:
          - $ref: '#/components/schemas/magic-visibility_messages'
          example: []
        result:
          enum:
          - null
          type:
          - object
          - 'null'
        success:
          description: Whether the API call was successful
          enum:
          - false
          example: false
          type: boolean
      required:
      - success
      - errors
      - messages
      - result
      type: object
    magic-visibility_api-response-single:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-common'
      - properties:
          result:
            anyOf:
            - type:
              - object
              - 'null'
            - type:
              - string
              - 'null'
      type: object
    magic-visibility_pcaps_id:
      description: The ID for the packet capture.
      example: 66802ca5668e47a2b82c2e6746e45037
      maxLength: 32
      minLength: 32
      type: string
    magic-visibility_api-response-common:
      properties:
        errors:
          $ref: '#/components/schemas/magic-visibility_messages'
        messages:
          $ref: '#/components/schemas/magic-visibility_messages'
        result:
          anyOf:
          - type: object
          - items: {}
            type: array
          - type: string
        success:
          description: Whether the API call was successful
          enum:
          - true
          example: true
          type: boolean
      required:
      - success
      - errors
      - messages
      - result
      type: object
    magic-visibility_pcaps_request_full:
      properties:
        byte_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_byte_limit'
        colo_name:
          $ref: '#/components/schemas/magic-visibility_pcaps_colo_name'
        destination_conf:
          $ref: '#/components/schemas/magic-visibility_pcaps_destination_conf'
        filter_v1:
          $ref: '#/components/schemas/magic-visibility_pcaps_filter_v1'
        packet_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_packet_limit'
        system:
          $ref: '#/components/schemas/magic-visibility_pcaps_system'
        time_limit:
          $ref: '#/components/schemas/magic-visibility_pcaps_time_limit'
        type:
          $ref: '#/components/schemas/magic-visibility_pcaps_type'
      required:
      - time_limit
      - type
      - system
      - colo_name
      - destination_conf
      type: object
    magic-visibility_pcaps_colo_name:
      description: The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to `full` packet captures.
      example: ord02
      type: string
    magic-visibility_pcaps_packet_limit:
      description: The limit of packets contained in a packet capture.
      example: 10000
      maximum: 10000
      minimum: 1
      type: number
    magic-visibility_pcaps_single_response:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-single'
      - properties:
          result:
            anyOf:
            - $ref: '#/components/schemas/magic-visibility_pcaps_response_simple'
            - $ref: '#/components/schemas/magic-visibility_pcaps_response_full'
    magic-visibility_pcaps_ownership_response:
      properties:
        destination_conf:
          $ref: '#/components/schemas/magic-visibility_pcaps_destination_conf'
        filename:
          $ref: '#/components/schemas/magic-visibility_pcaps_ownership_challenge'
        id:
          description: The bucket ID associated with the packet captures API.
          example: 9883874ecac311ec8475433579a6bf5f
          maxLength: 32
          minLength: 32
          type: string
        status:
          description: The status of the ownership challenge. Can be pending, success or failed.
          enum:
          - pending
          - success
          - failed
          example: success
          type: string
        submitted:
          description: The RFC 3339 timestamp when the bucket was added to packet captures API.
          example: '2020-01-01T08:00:00Z'
          type: string
        validated:
          description: The RFC 3339 timestamp when the bucket was validated.
          example: '2020-01-01T08:00:00Z'
          type: string
      required:
      - id
      - status
      - submitted
      - destination_conf
      - filename
      type: object
    magic-visibility_pcaps_system:
      description: The system used to collect packet captures.
      enum:
      - magic-transit
      example: magic-transit
      type: string
    magic-visibility_pcaps_ownership_single_response:
      allOf:
      - $ref: '#/components/schemas/magic-visibility_api-response-common'
      - properties:
          result:
            $ref: '#/components/schemas/magic-visibility_pcaps_ownership_response'
    magic-visibility_pcaps_filter_v1:
      description: The packet capture filter. When this field is empty, all packets are captured.
      properties:
        destination_address:
          description: The destination IP address of the packet.
          example: 1.2.3.4
          type: string
        destination_port:
          description: The destination port of the packet.
          example: 80
          type: number
        protocol:
          description: The protocol number of the packet.
          example: 6
          type: number
        source_address:
          description: The source IP address of the packet.
          example: 1.2.3.4
          type: string
        source_port:
          description: The source port of the packet.
          example: 123
          type: number
      type: object
    magic-visibility_pcaps_submitted:
      description: The RFC 3339 timestamp when the packet capture was created.
      example: '2020-01-01T08:00:00Z'
      type: string
  securitySchemes:
    api_email:
      in: header
      name: X-Auth-Email
      type: apiKey
    api_key:
      in: header
      name: X-Auth-Key
      type: apiKey
    api_token:
      scheme: bearer
      type: http
    user_service_key:
      in: header
      name: X-Auth-User-Service-Key
      type: apiKey