tcpshield-api.yaml

openapi: 3.0.2
info:
  title: TCPShield API
  version: '1.0'
  description: |
    This is the official documentation for the REST endpoints of TCPShield.
    Information regarding this API can be found 
    [here](https://docs.tcpshield.com/premium-features).
servers:
  - url: 'https://api.tcpshield.com/'
components:
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
  schemas:
    CreateNetwork:
      type: object
      properties:
        name:
          type: string
    UpdateNetworkRequest:
      type: object
      properties:
        name:
          type: string
        connections_per_second_threshold:
          type: integer
        client_ban_seconds:
          type: integer
        client_allow_seconds:
          type: integer
        mitigation_message:
          type: string
    NetworkResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        premium:
          type: boolean
        protected_cname:
          type: string
        txt_verification:
          type: string
        connections_per_second_threshold:
          type: integer
        client_ban_seconds:
          type: integer
        client_allow_seconds:
          type: integer
        mitigation_message:
          type: string
        vpn_block:
          type: boolean
        webhook_url:
          type: string
        attack_emails:
          type: boolean
        verification_server:
          type: boolean
        antivpn_kick_msg:
          type: string
        forward_true_slp:
          type: boolean
        offline_motd_enabled:
          type: boolean
        offline_motd:
          type: string
        offline_kick_message:
          type: string
        offline_favicon:
          type: string
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateBackendSetRequest:
      type: object
      properties:
        name:
          type: string
        backends:
          type: array
          items:
            type: string
        proxy_protocol:

          type: boolean
        vulcan_ac_enabled:
          type: boolean
        load_balancing_mode:
          type: integer
    CreateBackendSetResponse:
      type: object
      properties:
        id:
          type: integer
    UpdateBackendSetRequest:
      type: object
      properties:
        name: 
          type: string
        backends:
          type: array
          items:
            type: string
    DomainResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        backend_set_id:
          type: integer
        bac:
          type: boolean
        verified:
          type: boolean
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    IPFirewallResponse:
      type: object
      properties:
        id:
          type: integer
        cidr:
          type: string
        whitelist:
          type: boolean
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateIPFirewallRequest:
      type: object
      properties:
        cidr:
          type: string
        whitelist:
          type: boolean
    ASNFirewallResponse:
      type: object
      properties:
        id:
          type: integer
        asn:
          type: integer
        whitelist:
          type: boolean
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateASNFirewallRequest:
      type: object
      properties:
        asn:
          type: integer
        whitelist:
          type: boolean
    CountryFirewallResponse:
      type: object
      properties:
        id:
          type: integer
        country_id:
          type: integer
        country_code:
          type: string
        country_name:
          type: string
        whitelist:
          type: boolean
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateCountryFirewallRequest:
      type: object
      properties:
        country_id:
          type: integer
        whitelist:
          type: boolean
    BedrockTunnelsResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        backend_set_id:
          type: integer
        location:
          type: string
        proxy_protocol:
          type: integer
        allocated_cname:
          type: string
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateBedrockTunnelsRequest:
      type: object
      properties:
        name:
          type: string
        backend_set_id:
          type: integer
        location:
          type: string
        proxy_protocol:
          type: integer
    BedrockTunnelsLocationsResponse:
      type: string
    BedrockCertificateResponse:
      type: object
      description: |
        A TLS certificate served by the Bedrock proxies for the network's NetherNet (HTTPS) signaling.
        Certificate and key material is never returned; the `names`, dates, issuer and status are.
      properties:
        id:
          type: integer
        display_name:
          type: string
          description: Human-readable name (the apex or hostname the certificate was requested for)
        names:
          type: array
          description: DNS names (SANs) the certificate covers, lowercase, wildcards included
          items:
            type: string
        type:
          type: string
          enum: [managed, uploaded]
          description: '`managed` is issued and renewed by TCPShield via ACME; `uploaded` was supplied by you'
        status:
          type: string
          enum: [pending_dns, issuing, active, failed, expired]
          description: |
            Managed certificates start as `pending_dns` until the delegation CNAME is found, move to
            `issuing` while the order runs, then `active`. `failed` keeps `last_error`. Uploaded
            certificates are `active` immediately and become `expired` after `not_after`.
        challenge_name:
          type: string
          description: Managed only. The DNS name you must create a CNAME record for (`_acme-challenge.<apex or hostname>`)
        delegation_target:
          type: string
          description: Managed only. The target the `challenge_name` CNAME must point at
        not_before:
          type: string
          format: date-time
          nullable: true
        not_after:
          type: string
          format: date-time
          nullable: true
        issuer:
          type: string
        last_error:
          type: string
          description: Last issuance or renewal error for managed certificates, empty when none
        last_attempt_at:
          type: string
          format: date-time
          nullable: true
        renewal_failing:
          type: boolean
          description: True for an active managed certificate whose most recent renewal attempt failed
        chain_warning:
          type: string
          description: Only present on the create response of an upload whose chain does not build to a publicly trusted root
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateBedrockCertificateRequest:
      type: object
      required:
        - type
      description: |
        Set `type` and the fields for that type. For `managed`, send `hostname` and optionally `scope`.
        For `uploaded`, send `certificate`, `private_key` and optionally `chain` as PEM text.
      properties:
        type:
          type: string
          enum: [managed, uploaded]
        hostname:
          type: string
          description: Managed only. A fully qualified hostname such as `play.example.com`. Must not be an IP address or a public suffix
        scope:
          type: string
          enum: [apex_wildcard, hostname_only]
          default: apex_wildcard
          description: |
            Managed only. `apex_wildcard` issues for the registrable domain and its wildcard
            (`example.com`, `*.example.com`); `hostname_only` issues for the exact hostname.
        certificate:
          type: string
          description: Uploaded only. Exactly one PEM-encoded CERTIFICATE block (the leaf)
        chain:
          type: string
          description: Uploaded only. Zero or more PEM-encoded intermediate CERTIFICATE blocks
        private_key:
          type: string
          description: Uploaded only. PEM-encoded RSA (2048 bits or more), EC (P-256 or P-384) or PKCS#8 key without a passphrase. Ed25519 is not supported by Minecraft clients
    BedrockCertificateMutationResponse:
      type: object
      properties:
        status:
          type: integer
          description: 0 on success
        message:
          type: string
        data:
          $ref: '#/components/schemas/BedrockCertificateResponse'
    BedrockCertificateSuggestionResponse:
      type: object
      properties:
        apex:
          type: string
          description: Registrable domain of one or more verified Java domains on the network that no certificate covers yet
        from:
          type: array
          description: The verified domains the apex was derived from
          items:
            type: string
    BedrockCertificateErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: 1 on error
        error:
          type: string
    AnalyticsBounceRateResponse:
      type: object
      properties:
        value:
          type: number
          format: float
    AnalyticsTopDomainsResponse:
      type: object
      properties:
        key:
          type: string
        value:
          type: integer
    AnalyticsUniqueUsersResponse:
      type: object
      properties:
        value:
          type: integer
    AnalyticsRetentionResponse:
      type: object
    AnalyticsMitigatedCountResponse:
      type: object
      properties:
        value:
          type: integer
    AnalyticsMcVersionBreakdownResponse:
      type: object
    UserSummaryResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
        data:
          type: object
          properties:
            id:
              type: integer
            firstname:
              type: string
            lastname:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
            account_limited:
              type: boolean
            balance:
              type: number
              format: float
            plan_id:
              type: integer
            plan_name:
              type: string
            plan_expiry:
              type: string
              format: date-time
            two_factor_enabled:
              type: boolean
            verified:
              type: boolean
            notifications:
              type: array
              items:
                type: string
            commit_level:
              type: string
            updated_at:
              type: string
              format: date-time
            created_at:
              type: string
              format: date-time
    UpdateUserEmailRequest:
      type: object
      properties:
        email:
          type: string
        emailconfirm:
          type: string
    UserApiKeyResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            key:
              type: string
    UpdateUserGeneralInfoRequest:
      type: object
      properties:
        firstname:
          type: string
        lastname:
          type: string
        phone:
          type: string
    UpdateUserPasswordRequest:
      type: object
      properties:
        old_password:
          type: string
        new_password:
          type: string
        new_password_confirm:
          type: string
    BackendSetResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        proxy_protocol:
          type: boolean
        vulcan_ac_enabled:
          type: boolean
        load_balancing_mode:
          type: integer
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateDomainRequest:
      type: object
      properties:
        name:
          type: string
        backend_set_id:
          type: integer
        bac:
          type: boolean
    UpdateDomainRequest:
      type: object
      properties:
        name:
          type: string
        backend_set_id:
          type: integer
        bac:
          type: boolean
    CreateDomainResponse:
      type: object
      properties:
        id:
          type: integer
    PreVerifyDomainRequest:
      type: object
      properties:
        domain_name:
          type: string
    SubUserResponse:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        full_name: 
          type: string
        verified:
          type: boolean
        perms:
          type: object
          properties:
            read_network:
              type: boolean
            update_network:
              type: boolean
            delete_network:
              type: boolean
            create_network_user:
              type: boolean
            read_network_user:
              type: boolean
            update_network_user:
              type: boolean
            delete_network_user:
              type: boolean
            create_domains:
              type: boolean
            read_domains:
              type: boolean
            update_domains:
              type: boolean
            delete_domains:
              type: boolean
            create_backends:
              type: boolean
            read_backends:
              type: boolean
            update_backends:
              type: boolean   
            delete_backends:
              type: boolean   
            updated_at:
              type: string
              format: date-time
            created_at:
              type: string
              format: date-time
    SentryTunnelResponse:
      type: object
      properties:
        id:
          type: integer
          format: uint
          description: Unique identifier for the sentry tunnel
        name:
          type: string
          description: Name of the sentry tunnel
        endpoint_public_key:
          type: string
          description: Public key of the endpoint
        endpoint_private_key:
          type: string
          description: Private key of the endpoint
        endpoint_peer:
          type: string
          description: Peer endpoint information
        bind_port:
          type: integer
          description: Port to which the tunnel is bound
        location:
          type: string
          description: Location of the sentry tunnel
        current_bandwidth_usage:
          type: integer
          format: uint64
          description: Current bandwidth usage in bytes
        month_bandwidth_usage:
          type: integer
          format: uint64
          description: Bandwidth usage for the current month in bytes
        cumulative_bandwidth_usage:
          type: integer
          format: uint64
          description: Total bandwidth usage in bytes
        created_at:
          type: string
          format: date-time
          description: Timestamp when the tunnel was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the tunnel was last updated
        ingress:
          type: integer
          format: uint64
          description: Ingress bandwidth usage in bytes
        egress:
          type: integer
          format: uint64
          description: Egress bandwidth usage in bytes
        tunnel_addresses:
          type: array
          items:
            $ref: "#/components/schemas/TunnelAddressResponse"
          description: List of tunnel addresses associated with the tunnel
        tunnel_users:
          type: array
          items:
            $ref: "#/components/schemas/TunnelUserResponse"
          description: List of users associated with the tunnel
    TunnelAddressResponse:
      type: object
      properties:
        ip_address_public:
          type: string
          description: Public IP address of the tunnel
        ip_address_private:
          type: string
          description: Private IP address of the tunnel
        peer_ip_address_private:
          type: string
          description: Private IP address of the tunnel peer
        location:
          type: string
          description: Location associated with the tunnel address
    TunnelUserResponse:
      type: object
      properties:
        verified:
          type: boolean
          nullable: true
          description: Indicates if the user is verified
        tunnel_id:
          type: integer
          format: uint
          description: ID of the associated tunnel
        user_id:
          type: integer
          format: uint
          description: ID of the user associated with the tunnel
        permission_id:
          type: integer
          format: uint
          description: ID of the permission level assigned to the user
    SentryTunnelLocations:
      type: object
      additionalProperties:
        type: string
      example:
        ANY: "Anycast"
      description: A mapping of location identifiers to their human-readable names.
    SentryTunnelSetupScriptResponse:
      type: object
      properties:
        status:
          type: integer
          description: Status code of the response
        data:
          type: string
          description: The startup script content
    SentryTunnelAnalyticsResponse:
      type: object
      properties:
        egress:
          type: array
          items:
            $ref: "#/components/schemas/Float64ValueTime"
          description: Egress bandwidth data points
        ingress:
          type: array
          items:
            $ref: "#/components/schemas/Float64ValueTime"
          description: Ingress bandwidth data points
        max:
          type: number
          format: float
          description: Maximum recorded value
    Float64ValueTime:
      type: object
      properties:
        value:
          type: number
          format: float
          description: The recorded value
        time:
          type: string
          format: date-time
          description: The timestamp of the recorded value
    SentryTunnelFirewallResponse:
      type: object
      properties:
        id:
          type: integer
          format: uint
          description: Unique identifier for the firewall rule
        start_port:
          type: integer
          format: uint
          description: Starting port of the firewall rule
        end_port:
          type: integer
          format: uint
          description: Ending port of the firewall rule
        is_active:
          type: boolean
          description: Indicates if the firewall rule is active
        internal_name:
          type: string
          description: Internal name of the firewall rule
        human_name:
          type: string
          description: Human-readable name of the firewall rule
        filter_id:
          type: integer
          format: uint
          description: Identifier of the associated filter
        created_at:
          type: string
          format: date-time
          description: Timestamp when the firewall rule was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the firewall rule was last updated
    CreateSentryTunnelRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the sentry tunnel
          minLength: 3
          maxLength: 50
        endpoint_peer:
          type: string
          description: Peer endpoint information
          maxLength: 128
        location:
          type: string
          description: Location of the sentry tunnel (optional)
        bind_port:
          type: integer
          description: Port to which the tunnel is bound
          minimum: 1
          maximum: 65535
      required:
        - name
        - endpoint_peer
        - bind_port
    UpdateSentryTunnelRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the sentry tunnel
          minLength: 3
          maxLength: 50
        endpoint_public_key:
          type: string
          description: Public key of the endpoint
          maxLength: 64
        endpoint_peer:
          type: string
          description: Peer endpoint information
          maxLength: 128
        bind_port:
          type: integer
          description: Port to which the tunnel is bound
          minimum: 1
          maximum: 65535
      required:
        - name
        - endpoint_public_key
        - endpoint_peer
        - bind_port
    CreateSentryTunnelFirewallRequest:
      type: object
      properties:
        start_port:
          type: integer
          description: Starting port of the firewall rule
          minimum: 1
          maximum: 65535
        end_port:
          type: integer
          description: Ending port of the firewall rule
          minimum: 1
          maximum: 65535
        filter_id:
          type: integer
          description: Identifier of the associated filter
          minimum: 1
        is_active:
          type: boolean
          description: Indicates if the firewall rule is active
      required:
        - start_port
        - end_port
        - filter_id
    UpdateSentryTunnelFirewallRequest:
      type: object
      properties:
        start_port:
          type: integer
          description: Starting port of the firewall rule
          minimum: 1
          maximum: 65535
        end_port:
          type: integer
          description: Ending port of the firewall rule
          minimum: 1
          maximum: 65535
        filter_id:
          type: integer
          description: Identifier of the associated filter
          minimum: 1
        is_active:
          type: boolean
          description: Indicates if the firewall rule is active
      required:
        - start_port
        - end_port
        - filter_id
tags:
  - name: Network
    description: Network abilities
  - name: Domain
    description: CRUD operations to manage domains on TCPShield
  - name: Backends
    description: Abilities related to the management of hosts
  - name: User
    description: User abilities
  - name: Firewall
    description: Network firewall abilities
  - name: AsnFirewall
    description: Network ASN firewall firewall abilities
  - name: CountryFirewall
    description: Network country firewall abilities
  - name: BedrockTunnels
    description: Bedrock tunnels abilities
  - name: BedrockCertificates
    description: TLS certificates for Bedrock NetherNet (HTTPS) signaling
  - name: Analytics
    description: Analytics abilities
  - name: SentryTunnels
    description: Sentry tunnel abilities
paths:
  /networks:
    get:
      description: Fetch list of available networks
      parameters: []
      tags: 
        - Network
      responses:
        '200': 
          description: "OK"
          content:
            application/json:
              schema: 
                type: array
                items: 
                  $ref: '#/components/schemas/NetworkResponse'
    post:
      description: Add new network to the account
      parameters: []
      tags:
        - Network
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetwork'
      responses:
        '200':
          description: OK
        '403':
          description: Permission denied add networks
  '/networks/{networkId}':
    get:
      description: Fetch info for a single network
      tags:
        - Network
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/NetworkResponse'
        '404':
          description: Network not found
    patch:
      description: Update information on a network
      tags:
        - Network
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkRequest'
      responses:
        '200':
          description: OK
        '403':
          description: Permission denied to update this network
        '404':
          description: Network not found
    delete:
      description: Delete a network
      tags:
        - Network
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '403':
          description: Permission denied to delete this network
        '404':
          description: Network not found
  '/networks/{networkId}/domains':
    get:
      description: Fetch a list of domains attached to a network
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID 
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/DomainResponse'
    post:
      description: Add a domain to a network
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDomainRequest'
      responses:
        '200':
          description: Created
        '403':
          description: Permission denied to edit this network
        '409':
          description: 'Domain already exists in our system, could be attached to another network'
  '/networks/{networkId}/domains/{domainId}':
    get:
      description: Fetch a single domain
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: domainId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/DomainResponse'
        '404':
          description: Domain not found
    patch:
      description: Update a domain attached to a network
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: domainId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDomainRequest'
      responses:
        '200':
          description: OK
        '403':
          description: Permission denied to edit this domain
        '404':
          description: Domain not found
    delete:
      description: Delete a domain attached to a network
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: domainId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '404':
          description: Domain not found
  '/networks/{networkId}/domains/preverify':
    post:
      description: Helper method to check if a domain is already verified before adding.
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreVerifyDomainRequest'
      responses:
        '200':
          description: Standard API response to check if domain is verified or not. 
        '404':
          description: Network not found
  '/networks/{networkId}/domains/{domainID}/verify':
    get:
      description: Helper method to check if a domain is already verified before adding.
      tags:
        - Domain
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: domainID
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Standard API response to check if domain is verified or not. 
        '404':
          description: Domain not found
  '/networks/{networkId}/backendSets':
    get:
      description: List backend sets for a network
      tags:
        - Backends
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/BackendSetResponse'
        '404':
          description: Network not found
    post:
      description: Create a new backend set
      tags:
        - Backends
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBackendSetRequest'
      responses:
        '200':
          description: Successfully Created
        '404':
          description: Network not found
  '/networks/{networkId}/backendSets/{setId}':
    get:
      description: Get information about a backend set
      tags:
        - Backends
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: setId
        - name: setId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/BackendSetResponse'
        '404':
          description: Backend set not found
    patch:
      description: Update backend sets
      tags:
        - Backends
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: setId
        - name: setId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBackendSetRequest'
      responses:
        '200':
          description: Succesfully Updated
        '404':
          description: Domain not found
    delete:
      description: Delete a set of backends.
      tags:
        - Backends
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: setId
        - name: setId
          in: path
          description: Domain ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Deleted
        '404':
          description: Domain not found
  '/networks/{networkId}/firewall':
    get:
      description: Get information about a network firewalls
      tags:
        - Firewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IPFirewallResponse'
        '404':
          description: Firewall not found
    post:
      description: Add network firewall
      tags:
        - Firewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIPFirewallRequest'
      responses:
        '200':
          description: Successfully Updated
        '500':
          description: Firewall not created
  '/networks/{networkId}/firewall/{firewallEntryID}':
    delete:
      description: Delete a firewall
      tags:
        - Firewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: firewallEntryID
          in: path
          description: EntryID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '404':
          description: Firewall not found
  '/networks/{networkId}/asnFirewall':
    get:
      description: Get information about a network ASN firewalls
      tags:
        - AsnFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ASNFirewallResponse'
        '404':
          description: ASN Firewall not found
    post:
      description: Add network ASN firewall
      tags:
        - AsnFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateASNFirewallRequest'
      responses:
        '200':
          description: Successfully Updated
        '500':
          description: ASN Firewall not created
  '/networks/{networkId}/asnFirewall/{firewallEntryID}':
    delete:
      description: Delete a ASN firewall
      tags:
        - AsnFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: firewallEntryID
          in: path
          description: EntryID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '404':
          description: ASN Firewall not found
  '/networks/{networkId}/countryFirewall':
    get:
      description: Get information about a network Country firewalls
      tags:
        - CountryFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountryFirewallResponse'
        '404':
          description: Country Firewall not found
    post:
      description: Add network Country firewall
      tags:
        - CountryFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCountryFirewallRequest'
      responses:
        '200':
          description: Successfully Updated
        '500':
          description: Country Firewall not created
  '/networks/{networkId}/countryFirewall/{firewallEntryID}':
    delete:
      description: Delete a Country firewall
      tags:
        - CountryFirewall
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: firewallEntryID
          in: path
          description: EntryID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '404':
          description: Country Firewall not found
  '/networks/{networkId}/bedrockTunnels':
    get:
      description: Get information about a network bedrock tunnels
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BedrockTunnelsResponse'
        '404':
          description: Bedrock Tunnels not found
    post:
      description: Add network Bedrock Tunnels
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBedrockTunnelsRequest'
      responses:
        '200':
          description: Successfully Updated
        '500':
          description: Bedrock Tunnels not created
  '/networks/{networkId}/bedrockTunnels/locations':
    get:
      description: List available bedrock tunnel locations
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BedrockTunnelsLocationsResponse'
        '404':
          description: Bedrock Tunnels not found
  '/networks/{networkId}/bedrockTunnels/{tunnelId}':
    get:
      description: Get information about a network bedrock tunnel
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: tunnelId
          in: path
          description: Tunnel ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockTunnelsResponse'
        '404':
          description: Bedrock Tunnel not found
    patch:
      description: Update network Bedrock Tunnel
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: tunnelId
          in: path
          description: Tunnel ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBedrockTunnelsRequest'
      responses:
        '200':
          description: Successfully Updated
        '500':
          description: Bedrock Tunnels not updated
    delete:
      description: Delete a bedrock tunnels
      tags:
        - BedrockTunnels
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: tunnelId
          in: path
          description: Tunnel ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '404':
          description: Bedrock Tunnel not found
  '/networks/{networkId}/bedrockCertificates':
    get:
      description: List the network's Bedrock certificates. Certificate and key material is never returned.
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BedrockCertificateResponse'
        '404':
          description: Network not found
    post:
      description: |
        Add a Bedrock certificate. Requires the network owner to be on the Pro plan or above.

        **Managed** (`type: managed`): the certificate is created in `pending_dns` and the response
        carries `challenge_name` and `delegation_target`. Create a CNAME record from `challenge_name`
        to `delegation_target` at your DNS provider. TCPShield checks for it about once a minute (or
        immediately via the `check` endpoint), then issues the certificate through ACME and renews it
        automatically. A name may only be covered by one certificate per network; at most 10
        certificates may be waiting for DNS at once.

        **Uploaded** (`type: uploaded`): the PEM material is validated (key matches the leaf, leaf is a
        current server certificate with at least one DNS name, key strength) and stored `active`
        immediately. The private key is encrypted at rest. If the supplied chain does not build to a
        publicly trusted root the certificate is still accepted and the response includes
        `chain_warning`. Request bodies are limited to 1 MiB.
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBedrockCertificateRequest'
      responses:
        '200':
          description: Certificate created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockCertificateMutationResponse'
        '400':
          description: Invalid payload, hostname or PEM material (the error text says what is wrong)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockCertificateErrorResponse'
        '403':
          description: Permission denied, or the network owner's plan does not include Bedrock certificates
        '404':
          description: Network not found
        '409':
          description: A certificate covering one of the names already exists on this network
        '429':
          description: Too many certificates are waiting for DNS on this network
  '/networks/{networkId}/bedrockCertificates/suggestions':
    get:
      description: |
        List registrable domains of the network's verified Java domains that no Bedrock certificate
        covers yet. Useful for suggesting what to issue a managed certificate for.
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BedrockCertificateSuggestionResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/bedrockCertificates/{certId}':
    get:
      description: Get one Bedrock certificate
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: certId
          in: path
          description: Certificate ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockCertificateResponse'
        '404':
          description: Network or certificate not found
    delete:
      description: |
        Delete a Bedrock certificate. The proxies stop serving it within seconds. For a managed
        certificate the delegation CNAME you created becomes inert and can be removed.
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: certId
          in: path
          description: Certificate ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Certificate deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockCertificateMutationResponse'
        '403':
          description: Permission denied
        '404':
          description: Network or certificate not found
  '/networks/{networkId}/bedrockCertificates/{certId}/check':
    post:
      description: |
        Run the DNS check for a managed certificate now instead of waiting for the next scheduled
        pass, and start issuance if the delegation CNAME is in place. The response carries the
        certificate's current state. Rate limited to one check every few minutes per certificate.
      tags:
        - BedrockCertificates
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
        - name: certId
          in: path
          description: Certificate ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Check complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BedrockCertificateMutationResponse'
        '400':
          description: Only managed certificates can be checked
        '403':
          description: Permission denied, or the network owner's plan does not include Bedrock certificates
        '404':
          description: Network or certificate not found
        '429':
          description: Checked too recently, wait a few minutes
        '503':
          description: Certificate worker is not running
  '/networks/{networkId}/analytics/bounceRate':
    get:
      description: List analytics bounce rate
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsBounceRateResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/analytics/topDomains':
    get:
      description: List available analytics top domains
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsTopDomainsResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/analytics/uniqueUsers':
    get:
      description: List available analytics unique users
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsUniqueUsersResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/analytics/retention':
    get:
      description: List available analytics retention
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsRetentionResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/analytics/mitigatedCount':
    get:
      description: List available analytics mitigated count
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsMitigatedCountResponse'
        '404':
          description: Network not found
  '/networks/{networkId}/analytics/mcVersionBreakdown':
    get:
      description: List available analytics mc version breakdown
      tags:
        - Analytics
      parameters:
        - name: networkId
          in: path
          description: Network ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsMcVersionBreakdownResponse'
        '404':
          description: Network not found
  '/user/summary':
    get:
      description: Get current user information
      tags:
        - User
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSummaryResponse'
        '401':
          description: Unauthorized
  '/user/email':
    patch:
      description: Update current user email
      tags:
        - User
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserEmailRequest'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
  '/user/apikey':
    get:
      description: Get current user api key
      tags:
        - User
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApiKeyResponse'
        '401':
          description: Unauthorized
  '/user/apikey/regenerate':
    post:
      description: Regenerate current user api key
      tags:
        - User
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
  '/user/updateGeneralInfo':
    post:
      description: Update current user general info
      tags:
        - User
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGeneralInfoRequest'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
  '/user/password':
    post:
      description: Update current user password
      tags:
        - User
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserPasswordRequest'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
  '/tunnels':
    get:
      summary: List all sentry tunnels
      parameters: []
      tags:
        - SentryTunnels
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SentryTunnelResponse'
    post:
      summary: Add a new sentry tunnel
      parameters: []
      tags:
        - SentryTunnels
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSentryTunnelRequest'
      responses:
        '201':
          description: 'Tunnel created'
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelResponse'
  '/tunnels/locations':
    get:
      summary: List tunnel locations
      parameters: []
      tags:
        - SentryTunnels
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelLocations'
  '/tunnels/getBindPort':
    get:
      summary: Get bind port for a tunnel
      parameters: []
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: integer
  '/tunnels/{tunnelID}/setupScript':
    get:
      summary: Get setup script for a tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelSetupScriptResponse'
  '/tunnels/{tunnelID}/analytics':
    get:
      summary: Get analytics for a tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelAnalyticsResponse'
  '/tunnels/{tunnelID}':
    get:
      summary: Get a specific sentry tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SentryTunnelResponse'
        '404':
          description: Sentry tunnel not found
    put:
      summary: Update a specific sentry tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSentryTunnelRequest'
      responses:
        '200':
          description: Tunnel updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SentryTunnelResponse'
    delete:
      summary: Delete a specific sentry tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Tunnel deleted
  '/tunnelFilters':
    get:
      summary: List all tunnel filters
      parameters: []
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SentryTunnelFirewallResponse'
  '/tunnel/{tunnelID}/tunnelFirewall':
    post:
      summary: Add a firewall rule to a tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSentryTunnelFirewallRequest'
      responses:
        '201':
          description: Firewall rule added
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelFirewallResponse'
  '/tunnel/{tunnelID}/tunnelFirewalls':
    get:
      summary: List firewall rules for a tunnel
      parameters:
        - name: tunnelID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SentryTunnelFirewallResponse'
  '/tunnelFirewall/{filterID}':
    get:
      summary: Get details of a firewall filter
      parameters:
        - name: filterID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelFirewallResponse'
        '404':
          description: Firewall filter not found
    put:
      summary: Update a firewall filter
      parameters:
        - name: filterID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      requestBody:
        description: Structure
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSentryTunnelFirewallRequest'
      responses:
        '200':
          description: Filter updated
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SentryTunnelFirewallResponse'
    delete:
      summary: Delete a firewall filter
      parameters:
        - name: filterID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      tags:
        - SentryTunnels
      responses:
        '200':
          description: Filter deleted

security: 
  - APIKeyAuth: []