Skip to content

Create a distribution

Synchronous: answers 201 with status deploying; status becomes deployed once every edge has it.

POST
https://cdn.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/distributions

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

Header parameters

  • Idempotency-Keyoptionalstring

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

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

Request bodyJSONrequired

  • namestringrequired
    maxLength: 100, minLength: 1
  • originobjectrequired

    Either host and protocol (with port and hostHeader optional), or bucket alone.

    5 properties
    • bucketoptionalstring | null

      An Object Storage bucket of this organization, by name, read privately: the bucket's settings must list this distribution in cdnDistributions. Only GET and HEAD of an object are served. Can't be combined with the other fields.

      pattern: ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$
    • hostoptionalstring

      A public DNS name, IPv4 address or IPv6 address (canonical form, no brackets). Edges connect over IPv4 when the name has an A record and over IPv6 otherwise. Private, loopback and EZGH platform addresses are refused, here and at the edge after every DNS resolution.

    • hostHeaderoptionalviewerororiginornull

      The Host header sent to the origin: the viewer's, or host.

      Default: "viewer"
    • portoptionalinteger | null

      Default 443 for https, 80 for http.

      maximum: 65535, minimum: 1
    • protocoloptionalhttporhttps

      With https, the origin's certificate is verified against host.

  • descriptionoptionalstring | null
    maxLength: 1000
  • domainsoptionalarray | null

    Your own domains, at most 10. A hostname is served by one distribution at a time: one another distribution has, or had until every edge stopped serving it, is 409.

  • enabledoptionalboolean | null
    Default: true
  • rewritesoptionalarray | null

    Path rewrites, at most 10, tried in order: the first whose pattern matches the request's path wins, and a path none matches is sent to the origin as it is. Left out of a replace, the distribution has none.

  • ssooptionalSSOInputornull

    Sign-in with EZGH SSO. Left out of a replace, it's turned off.

    2 variants

    One of the following:

    • SSOInput
      1 properties
      • requiredbooleanrequired

        Require sign-in with EZGH SSO. Refused (409) when the organization has no directory; can't be combined with a wildcard domain or a bucket origin.

    • null
  • tagsoptionalTagsornull
    2 variants

    One of the following:

  • wafoptionalDistributionWAFInputornull

    Attach a WAF (needs waf.wafs.attach on it), or null to detach one. Left out of a replace, the attached WAF stays.

    2 variants

    One of the following:

Returns

201

The distribution.

JSON
  • createdAtstringrequired
    format: date-time
  • defaultHostnamestringrequired

    d<12>.ezghcdn.com: CNAME your domains here. Never changes and is never reused.

  • descriptionstring | nullrequired
  • domainsarray ofobjectrequired
    2 properties
    • certificateIdstringrequired
    • hostnamestringrequired
  • enabledbooleanrequired

    false keeps the distribution, and edges refuse its hostnames with 421.

  • idstringrequired
    format: uuid
  • namestringrequired
  • organizationIdstringrequired
    format: uuid
  • originobjectrequired
    5 properties
    • bucketstring | nullrequired

      The Object Storage bucket the distribution reads, by name; null for any other origin. host, port, protocol and hostHeader are then the bucket's S3 endpoint.

    • hoststringrequired
    • hostHeaderviewerororiginrequired
    • portintegerrequired
    • protocolhttporhttpsrequired
  • projectIdstringrequired
    format: uuid
  • regionstringrequired
  • resourceNamestringrequired
  • rewritesarray ofobjectrequired
    2 properties
    • patternstringrequired

      A regular expression (RE2 syntax) matched against the request's path, anywhere in it unless anchored with ^ and $. ^/[^.]*$ matches every path without a dot.

      maxLength: 256, minLength: 1
    • replacementstringrequired

      The path sent to the origin instead, starting with /; $1 is the pattern's first capture group. The query string is kept, and the viewer's URL doesn't change. /index.html serves a single-page app's shell.

      maxLength: 256
  • slugstringrequired
  • ssoobjectrequired
    3 properties
    • applicationIdstring | nullrequired

      The distribution's application in EZGH SSO, where its assignments decide who gets in. Read-only.

    • issuerstring | nullrequired

      Where people sign in now: the directory's custom sign-in domain when it has one. Null while sign-in refuses everyone because the directory was deleted. Read-only.

    • requiredbooleanrequired

      Only people assigned to the distribution's application in the organization's EZGH SSO directory get through; anyone else is sent to sign in.

  • statusstringrequired

    deploying until every edge has the latest change, then deployed; clients treat others as unknown.

  • tagsmap ofstringrequired

    At most 50; keys 1-128 characters, values at most 256, keys starting with ezgh: are reserved.

  • updatedAtstringrequired
    format: date-time
  • wafDistributionWAFornullrequired

    The EZGH WAF the edges evaluate the distribution's requests against before the origin; null without one.

    2 variants

    One of the following:

    • 3 properties
      • statusdeployingoractiveorfailedrequired

        deploying until every edge enforces the WAF's current version; active when every edge does; failed when an edge refused it and keeps enforcing the version it had. Read-only.

      • versionintegerrequired

        The WAF version status refers to. Read-only.

        format: int64
      • wafIdstringrequired

        The attached waf_ WAF, in the distribution's project and region.

    • null

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