Skip to content

Create a listener

409 protocol_mismatch when a target group's protocol doesn't suit the listener (http groups for http and https listeners, tcp groups for tcp and tls), 409 rule_limit past 100 rules, and 409 target_group_not_found when an action names a target group that isn't this load balancer's or doesn't exist.

POST
https://lb-api.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/load-balancers/{loadBalancer}/listeners

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

  • loadBalancerstringrequired

Header parameters

  • Idempotency-Keyoptionalstring

    Makes a retry safe: the same key and request get the stored response.

    pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

  • portintegerrequired
  • protocoltcportlsorhttporhttpsrequired
  • additionalCertificatesoptionalarray ofstring

    SNI certificates beyond the default, at most 24: a client whose SNI one of them covers gets it, and any other client the default certificate. Each renews on its own. tls and https only; none twice, nor the default, nor a certificate with no DNS names (it can only be the default).

  • allowedSourceCidrsoptionalarray ofstring

    CIDRs allowed to connect: IPv4, and IPv6 where IPv6 is available. Each family admits only the clients its own ranges cover: a list with no IPv6 range admits no IPv6 client. Defaults to everyone: ["0.0.0.0/0"], with "::/0" where IPv6 is available.

  • certificateoptionalstring

    Required on tls and https.

  • defaultActionoptionalobject

    Required on http and https, unless targetGroup is given. Only http and https listeners take one.

    4 properties
    • typeforwardorredirectorfixedResponserequired
    • fixedResponseoptionalFixedResponseInputornull
      2 variants

      One of the following:

      • 3 properties
        • statusCodeintegerrequired
          maximum: 599, minimum: 200
        • bodyoptionalstring

          UTF-8, at most 1024 bytes. Default empty.

        • contentTypeoptionaltext/plainortext/htmlorapplication/json

          Default text/plain.

      • null
    • forwardoptionalForwardInputornull
      2 variants

      One of the following:

      • 3 properties
        • targetGroupsarray ofobjectrequired

          Each request picks a group by weight; the sum of weights is above 0.

          2 properties
          • targetGroupstringrequired

            An http target group of the listener's load balancer.

          • weightoptionalinteger

            Required with more than one group; 0 never receives.

            maximum: 999, minimum: 0
        • requestHeaderModifieroptionalHeaderModifierInputornull

          Changes the request's headers before it goes to the target.

          2 variants

          One of the following:

        • responseHeaderModifieroptionalHeaderModifierInputornull

          Changes the target's response headers before they reach the client.

          2 variants

          One of the following:

      • null
    • redirectoptionalRedirectInputornull
      2 variants

      One of the following:

      • 5 properties
        • hostoptionalstring | null
          maxLength: 253
        • pathoptionalstring | null
          maxLength: 1024
        • portoptionalinteger | null
          maximum: 65535, minimum: 1
        • schemeoptionalhttporhttpsornull
        • statusCodeoptional301or302or307or308

          Default 302.

      • null
  • idleTimeoutSecondsoptionalinteger

    tcp and tls: 60-6000 seconds, default 350. http and https: 1-4000, default 60: the client keep-alive, the server timeout and the WebSocket tunnel timeout.

  • rulesoptionalarray ofobject

    Ordered: the first rule that matches a request acts on it, and the default action takes the rest. At most 100. Sent, it replaces the whole list. Only http and https listeners take them.

    3 properties
    • actionobjectrequired

      type names the one of forward, redirect and fixedResponse that is set; the others are null.

      4 properties
      • typeforwardorredirectorfixedResponserequired
      • fixedResponseoptionalFixedResponseInputornull
        2 variants

        One of the following:

        • 3 properties
          • statusCodeintegerrequired
            maximum: 599, minimum: 200
          • bodyoptionalstring

            UTF-8, at most 1024 bytes. Default empty.

          • contentTypeoptionaltext/plainortext/htmlorapplication/json

            Default text/plain.

        • null
      • forwardoptionalForwardInputornull
        2 variants

        One of the following:

        • 3 properties
          • targetGroupsarray ofobjectrequired

            Each request picks a group by weight; the sum of weights is above 0.

            2 properties
            • targetGroupstringrequired

              An http target group of the listener's load balancer.

            • weightoptionalinteger

              Required with more than one group; 0 never receives.

              maximum: 999, minimum: 0
          • requestHeaderModifieroptionalHeaderModifierInputornull

            Changes the request's headers before it goes to the target.

            2 variants

            One of the following:

          • responseHeaderModifieroptionalHeaderModifierInputornull

            Changes the target's response headers before they reach the client.

            2 variants

            One of the following:

        • null
      • redirectoptionalRedirectInputornull
        2 variants

        One of the following:

        • 5 properties
          • hostoptionalstring | null
            maxLength: 253
          • pathoptionalstring | null
            maxLength: 1024
          • portoptionalinteger | null
            maximum: 65535, minimum: 1
          • schemeoptionalhttporhttpsornull
          • statusCodeoptional301or302or307or308

            Default 302.

        • null
    • matchoptionalobject

      Fields AND together. Entries OR within hosts, paths and methods, and AND within headers and queryParams. An empty field matches anything.

      5 properties
      • headersoptionalarray ofobject
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
      • hostsoptionalarray ofstring

        Exact names, or *.example.com for any name ending in .example.com. Lowercase; the port is ignored.

        maxLength: 253
      • methodsoptionalarray ofstring

        Uppercase.

        maxLength: 32
      • pathsoptionalarray ofobject
        2 properties
        • typeexactorprefixrequired

          prefix matches on segment boundaries: /api matches /api and /api/x, not /apix.

        • valuestringrequired

          Starts with /; printable ASCII without space, # or ?.

          maxLength: 1024, minLength: 1
      • queryParamsoptionalarray ofobject
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
    • nameoptionalstring | null
      maxLength: 64
  • targetGroupoptionalstring

    Required on tcp and tls. On http and https, alone, a default action forwarding to it.

Returns

201

The listener. lastChange on the load balancer tracks it reaching service.

JSON
  • additionalCertificatesarray ofstringrequired

    SNI certificates beyond the default, at most 24: a client whose SNI one of them covers gets it, and any other client the default certificate. Each renews on its own. Empty on tcp and http.

  • allowedSourceCidrsarray ofstringrequired

    CIDRs allowed to connect: IPv4, and IPv6 where IPv6 is available. Each family admits only the clients its own ranges cover: a list with no IPv6 range admits no IPv6 client. Defaults to everyone: ["0.0.0.0/0"], with "::/0" where IPv6 is available.

  • certificatestring | nullrequired
  • createdAtstringrequired
    format: date-time
  • defaultActionActionornullrequired

    An http or https listener's action for a request no rule matches. Null on tcp and tls.

    2 variants

    One of the following:

  • idstringrequired
  • idleTimeoutSecondsintegerrequired
  • loadBalancerstringrequired
  • portintegerrequired
  • protocoltcportlsorhttporhttpsrequired
  • rulesarray ofobjectrequired

    Ordered: the first rule that matches a request acts on it, and the default action takes the rest. At most 100. Sent, it replaces the whole list. Empty on tcp and tls.

    3 properties
    • actionobjectrequired

      type names the one of forward, redirect and fixedResponse that is set; the others are null.

      4 properties
      • fixedResponseFixedResponseornullrequired
        2 variants

        One of the following:

        • 3 properties
          • bodystringrequired

            UTF-8, at most 1024 bytes. Default empty.

          • contentTypetext/plainortext/htmlorapplication/jsonrequired

            Default text/plain.

          • statusCodeintegerrequired
            maximum: 599, minimum: 200
        • null
      • forwardForwardornullrequired
        2 variants

        One of the following:

        • Forward
          3 properties
          • requestHeaderModifierHeaderModifierornullrequired

            Changes the request's headers before it goes to the target.

            2 variants

            One of the following:

          • responseHeaderModifierHeaderModifierornullrequired

            Changes the target's response headers before they reach the client.

            2 variants

            One of the following:

          • targetGroupsarray ofobjectrequired

            Each request picks a group by weight; the sum of weights is above 0.

            2 properties
            • targetGroupstringrequired

              An http target group of the listener's load balancer.

            • weightintegerrequired

              Required with more than one group; 0 never receives.

              maximum: 999, minimum: 0
        • null
      • redirectRedirectornullrequired
        2 variants

        One of the following:

        • Redirect
          5 properties
          • hoststring | nullrequired
            maxLength: 253
          • pathstring | nullrequired
            maxLength: 1024
          • portinteger | nullrequired
            maximum: 65535, minimum: 1
          • schemehttporhttpsornullrequired
          • statusCode301or302or307or308required

            Default 302.

        • null
      • typeforwardorredirectorfixedResponserequired
    • matchobjectrequired

      Fields AND together. Entries OR within hosts, paths and methods, and AND within headers and queryParams. An empty field matches anything.

      5 properties
      • headersarray ofobjectrequired
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
      • hostsarray ofstringrequired

        Exact names, or *.example.com for any name ending in .example.com. Lowercase; the port is ignored.

        maxLength: 253
      • methodsarray ofstringrequired

        Uppercase.

        maxLength: 32
      • pathsarray ofobjectrequired
        2 properties
        • typeexactorprefixrequired

          prefix matches on segment boundaries: /api matches /api and /api/x, not /apix.

        • valuestringrequired

          Starts with /; printable ASCII without space, # or ?.

          maxLength: 1024, minLength: 1
      • queryParamsarray ofobjectrequired
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
    • namestring | nullrequired
      maxLength: 64
  • targetGroupstring | nullrequired

    A tcp or tls listener's target group, and an http or https listener's when its default action forwards to exactly one; else null.

  • updatedAtstringrequired
    format: date-time

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close