API docs by Redocly

EncoraStream CDN API (2.0.0)

Download OpenAPI specification:

EncoraStream API Team: api-support@encorastream.com License: Proprietary

CDN and edge gateway management API for the EncoraStream platform.

Covers:

  • CDN endpoint management (distributions with custom hostnames, TLS, geo restrictions, compression)
  • Origin management (HTTP/HTTPS backends with health, TLS, retry, and SSRF controls)
  • Edge route management (host- and path-based routing with priority, redirects)
  • Cache rule management (TTL, browser/edge controls, cache keys, bypass, and stale policies)
  • Cache purge management (path, wildcard, tag-based purge with audit history)
  • Response headers policies (CORS, security headers, custom request/response headers)
  • Admin user management (create, update, deactivate, role assignment)
  • Audit logging (configuration, auth, purge, and admin events)
  • Configuration management (validate, publish, version, rollback, propagation)
  • System health (liveness, readiness, dependency checks)
  • Observability (metrics, edge node status, request and cache statistics)

Authorization Model

All write operations require a Bearer token with the admin role. Read-only endpoints (health, metrics) are unauthenticated or accept any valid token. API tokens are supported as an alternative to JWT for machine-to-machine access.

Distributions

CloudFront-style distribution management. Alias of CDN endpoints with distribution-scoped configuration.

List distributions

CloudFront-style alias for listing CDN endpoints.

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a distribution

CloudFront-style alias for creating a CDN endpoint.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string <= 100 characters
default_origin_id
required
string <uuid>
http_version
string
Default: "http2"
Enum: "http1.1" "http2" "http2and3"
ipv6_enabled
boolean
Default: true
response_headers_policy_id
string <uuid>
object (TlsConfig)

TLS settings applied to client-facing connections on this endpoint.

object (CompressionConfig)

Automatic response compression. The edge compresses responses if the client sends Accept-Encoding containing the configured algorithm and the response is compressible (text-based content type, no Content-Encoding already set, size ≥ min_size_bytes).

object (GeoRestriction)

Country-level access control. Uses the client IP address resolved to an ISO 3166-1 alpha-2 country code. VPN / proxy detection is not performed at this layer.

Array of objects (CustomErrorPage)
shield_region
string
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
default_origin_id
string <uuid>
http_version
string
Enum: "http1.1" "http2" "http2and3"
ipv6_enabled
boolean
response_headers_policy_id
string or null <uuid>
object (TlsConfig)

TLS settings applied to client-facing connections on this endpoint.

object (CompressionConfig)

Automatic response compression. The edge compresses responses if the client sends Accept-Encoding containing the configured algorithm and the response is compressible (text-based content type, no Content-Encoding already set, size ≥ min_size_bytes).

object (GeoRestriction)

Country-level access control. Uses the client IP address resolved to an ISO 3166-1 alpha-2 country code. VPN / proxy detection is not performed at this layer.

Array of objects (CustomErrorPage)
shield_region
string or null
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Resource not found.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

List origins for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an origin for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
url
string <uri> <= 2048 characters

Optional convenience form. Current Rails implementation accepts split scheme, host, port, and path_prefix fields. Must use http or https. Unsafe protocols, bare IPs in private ranges, and loopback addresses are rejected unless allow_private_network is true.

scheme
string
Default: "https"
Enum: "http" "https"
host
required
string <= 253 characters
port
integer [ 1 .. 65535 ]
Default: 443
path_prefix
string <= 2048 characters
Default: ""
enabled
boolean
Default: true
health_check_url
string <uri>

Dedicated health-check endpoint. Defaults to the origin root.

verify_tls
boolean
Default: true
allow_private_network
boolean
Default: false
ssrf_protection
boolean
Default: true
timeout_ms
integer [ 100 .. 60000 ]
Default: 30000
connect_timeout_ms
integer [ 100 .. 10000 ]
Default: 5000
max_retries
integer [ 0 .. 5 ]
Default: 2
retry_on
Array of strings
Default: ["connect_failure","5xx"]
Items Enum: "connect_failure" "5xx" 429 408
forward_host_header
boolean
Default: true
object
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "enabled": true,
  • "health_check_url": "http://example.com",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache behaviors for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache behavior for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache behaviors for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache behavior for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache policies for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache policy for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (CacheRuleMatch)

Path and method conditions that activate this cache rule. At least one of paths or content_types must be provided.

ttl_seconds
required
integer >= 0
browser_ttl_seconds
integer or null >= 0
object (CacheKey)

Controls which request attributes are included in the cache key. Reducing the key cardinality increases cache hit rates but may cause stale data to be served across different users or contexts.

object (CacheBypass)

Conditions under which caching is skipped entirely.

stale_while_revalidate_seconds
integer or null >= 0
stale_if_error_seconds
integer or null >= 0
cache_status_header
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "ttl_seconds": 0,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 0,
  • "stale_if_error_seconds": 0,
  • "cache_status_header": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List purge requests for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Purge cache for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
{
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List purge requests for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Purge cache for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
{
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List custom domains for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Attach a custom domain to a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
hostname
required
string <= 253 characters

Fully qualified domain name to attach (e.g. cdn.example.com). Wildcard hostnames (*.example.com) are supported with custom certificates only.

certificate_source
required
string
Enum: "managed" "custom"
object

Required when certificate_source is custom.

Responses

Request samples

Content type
application/json
{
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "custom_certificate": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List response headers policies for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a response headers policy for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
description
string <= 500 characters
object (CorsConfig)

Cross-Origin Resource Sharing policy applied to matched responses. When enabled, the CDN injects or overrides CORS headers on behalf of the origin. Requests with an Origin header not matching allow_origins receive no CORS headers.

object (SecurityHeadersConfig)

OWASP-recommended security response headers. Each header can be individually enabled and optionally set to override the origin value (default) or only fill when absent.

Array of objects (CustomHeaderEntry)
remove_response_headers
Array of strings[ items <= 256 characters ]
Array of objects (CustomHeaderEntry)
remove_request_headers
Array of strings[ items <= 256 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard Security Headers",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List signing keys for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a signing key for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
algorithm
string
Default: "HMAC-SHA256"
Enum: "HMAC-SHA256" "HMAC-SHA512"
secret
string >= 32 characters

Custom secret value. If omitted, the server generates a cryptographically secure 64-character secret automatically.

token_param
string
Default: "token"
expires_param
string
Default: "expires"
ip_binding_enabled
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "algorithm": "HMAC-SHA256",
  • "secret": "stringstringstringstringstringst",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production signing key",
  • "algorithm": "HMAC-SHA256",
  • "status": "active",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List IP access rules for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an IP access rule for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "block" "challenge"
cidr
required
string
description
string <= 255 characters
priority
integer [ 1 .. 1000 ]
Default: 100

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "cidr": "string",
  • "description": "string",
  • "priority": 100
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "allow",
  • "cidr": "203.0.113.0/24",
  • "description": "string",
  • "priority": 100,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List log drains for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a log drain for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
destination_type
required
string
Enum: "s3" "datadog" "elasticsearch" "http" "gcs"
destination_config
required
object
log_format
string
Default: "ndjson"
Enum: "json" "ndjson" "w3c_extended"
fields
Array of strings
endpoint_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "destination_type": "s3",
  • "destination_config": { },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Origins

Origin server management

List origins

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

enabled
boolean

Filter by enabled state.

health_status
string
Enum: "healthy" "degraded" "unhealthy" "unknown"

Filter by health status.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an origin

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
url
string <uri> <= 2048 characters

Optional convenience form. Current Rails implementation accepts split scheme, host, port, and path_prefix fields. Must use http or https. Unsafe protocols, bare IPs in private ranges, and loopback addresses are rejected unless allow_private_network is true.

scheme
string
Default: "https"
Enum: "http" "https"
host
required
string <= 253 characters
port
integer [ 1 .. 65535 ]
Default: 443
path_prefix
string <= 2048 characters
Default: ""
enabled
boolean
Default: true
health_check_url
string <uri>

Dedicated health-check endpoint. Defaults to the origin root.

verify_tls
boolean
Default: true
allow_private_network
boolean
Default: false
ssrf_protection
boolean
Default: true
timeout_ms
integer [ 100 .. 60000 ]
Default: 30000
connect_timeout_ms
integer [ 100 .. 10000 ]
Default: 5000
max_retries
integer [ 0 .. 5 ]
Default: 2
retry_on
Array of strings
Default: ["connect_failure","5xx"]
Items Enum: "connect_failure" "5xx" 429 408
forward_host_header
boolean
Default: true
object
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an origin

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an origin

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
url
string <uri> <= 2048 characters
scheme
string
Enum: "http" "https"
host
string <= 253 characters
port
integer [ 1 .. 65535 ]
path_prefix
string <= 2048 characters
enabled
boolean
health_check_url
string or null <uri>
verify_tls
boolean
allow_private_network
boolean
ssrf_protection
boolean
timeout_ms
integer [ 100 .. 60000 ]
connect_timeout_ms
integer [ 100 .. 10000 ]
max_retries
integer [ 0 .. 5 ]
retry_on
Array of strings
Items Enum: "connect_failure" "5xx" 429 408
forward_host_header
boolean
object
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "http://example.com",
  • "scheme": "http",
  • "host": "string",
  • "port": 1,
  • "path_prefix": "string",
  • "enabled": true,
  • "health_check_url": "http://example.com",
  • "verify_tls": true,
  • "allow_private_network": true,
  • "ssrf_protection": true,
  • "timeout_ms": 100,
  • "connect_timeout_ms": 100,
  • "max_retries": 5,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an origin

Deletes an origin. Fails with 409 Conflict if the origin is referenced by one or more active routes.

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Enable an origin

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable an origin

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List origins for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an origin for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
url
string <uri> <= 2048 characters

Optional convenience form. Current Rails implementation accepts split scheme, host, port, and path_prefix fields. Must use http or https. Unsafe protocols, bare IPs in private ranges, and loopback addresses are rejected unless allow_private_network is true.

scheme
string
Default: "https"
Enum: "http" "https"
host
required
string <= 253 characters
port
integer [ 1 .. 65535 ]
Default: 443
path_prefix
string <= 2048 characters
Default: ""
enabled
boolean
Default: true
health_check_url
string <uri>

Dedicated health-check endpoint. Defaults to the origin root.

verify_tls
boolean
Default: true
allow_private_network
boolean
Default: false
ssrf_protection
boolean
Default: true
timeout_ms
integer [ 100 .. 60000 ]
Default: 30000
connect_timeout_ms
integer [ 100 .. 10000 ]
Default: 5000
max_retries
integer [ 0 .. 5 ]
Default: 2
retry_on
Array of strings
Default: ["connect_failure","5xx"]
Items Enum: "connect_failure" "5xx" 429 408
forward_host_header
boolean
Default: true
object
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "enabled": true,
  • "health_check_url": "http://example.com",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Primary API Origin",
  • "url": "https://api-origin.encorastream.internal",
  • "scheme": "http",
  • "host": "api-origin.encorastream.internal",
  • "port": 443,
  • "path_prefix": "",
  • "protocol": "http",
  • "enabled": true,
  • "health_status": "healthy",
  • "health_check_url": "https://api-origin.encorastream.internal/healthz",
  • "verify_tls": true,
  • "allow_private_network": false,
  • "ssrf_protection": true,
  • "timeout_ms": 30000,
  • "connect_timeout_ms": 5000,
  • "max_retries": 2,
  • "retry_on": [
    ],
  • "forward_host_header": true,
  • "custom_headers": {
    },
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get origin health status

Returns the latest health check result for an origin. Health probes are sent automatically from each edge node at the interval configured on the origin. This endpoint returns the aggregated worst-case status across all edge nodes.

Authorizations:
BearerAuth
path Parameters
origin_id
required
string <uuid>

UUID of the origin resource.

Responses

Response samples

Content type
application/json
{
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "status": "healthy",
  • "latency_ms": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "failure_reason": "Connection refused (TCP)",
  • "consecutive_failures": 0,
  • "checked_at": "2019-08-24T14:15:22Z"
}

Routes

Edge route management

List routes

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

origin_id
string <uuid>

Filter by origin UUID.

enabled
boolean

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a route

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "Main API Route",
  • "origin_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f0001",
  • "priority": 100,
  • "match": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
origin_id
string <uuid>
enabled
boolean
priority
integer [ 0 .. 10000 ]
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string or null
response_headers_policy_id
string or null <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 10000,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Enable a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List routes

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

origin_id
string <uuid>

Filter by origin UUID.

enabled
boolean

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a route

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "Main API Route",
  • "origin_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f0001",
  • "priority": 100,
  • "match": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
origin_id
string <uuid>
enabled
boolean
priority
integer [ 0 .. 10000 ]
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string or null
response_headers_policy_id
string or null <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 10000,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Enable a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a route

Authorizations:
BearerAuth
path Parameters
route_id
required
string <uuid>

UUID of the route resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache behaviors for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache behavior for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache behaviors for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache behavior for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
origin_id
required
string <uuid>
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (RouteMatch)

Rules evaluated against the incoming request. All specified conditions must match (logical AND). At least one of hosts or paths must be provided.

strip_prefix
string
response_headers_policy_id
string <uuid>
Array of objects (RedirectRule)
compression_enabled
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "string",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Main API Route",
  • "origin_id": "fa284d86-c703-4b55-825c-a163977fd80a",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "strip_prefix": "/api/v2",
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "redirect_rules": [
    ],
  • "compression_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

CacheRules

Cache rule management

List cache rules

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

enabled
boolean

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache rule

Cache rules are validated before activation. Invalid rules return 422.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (CacheRuleMatch)

Path and method conditions that activate this cache rule. At least one of paths or content_types must be provided.

ttl_seconds
required
integer >= 0
browser_ttl_seconds
integer or null >= 0
object (CacheKey)

Controls which request attributes are included in the cache key. Reducing the key cardinality increases cache hit rates but may cause stale data to be served across different users or contexts.

object (CacheBypass)

Conditions under which caching is skipped entirely.

stale_while_revalidate_seconds
integer or null >= 0
stale_if_error_seconds
integer or null >= 0
cache_status_header
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "Static Assets Cache",
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 3600,
  • "stale_while_revalidate_seconds": 60,
  • "cache_key": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a cache rule

Authorizations:
BearerAuth
path Parameters
cache_rule_id
required
string <uuid>

UUID of the cache rule resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a cache rule

Authorizations:
BearerAuth
path Parameters
cache_rule_id
required
string <uuid>

UUID of the cache rule resource.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
enabled
boolean
priority
integer [ 0 .. 10000 ]
object (CacheRuleMatch)

Path and method conditions that activate this cache rule. At least one of paths or content_types must be provided.

ttl_seconds
integer >= 0
browser_ttl_seconds
integer or null >= 0
object (CacheKey)

Controls which request attributes are included in the cache key. Reducing the key cardinality increases cache hit rates but may cause stale data to be served across different users or contexts.

object (CacheBypass)

Conditions under which caching is skipped entirely.

stale_while_revalidate_seconds
integer or null >= 0
stale_if_error_seconds
integer or null >= 0
cache_status_header
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "priority": 10000,
  • "match": {
    },
  • "ttl_seconds": 0,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 0,
  • "stale_if_error_seconds": 0,
  • "cache_status_header": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a cache rule

Authorizations:
BearerAuth
path Parameters
cache_rule_id
required
string <uuid>

UUID of the cache rule resource.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Enable a cache rule

Authorizations:
BearerAuth
path Parameters
cache_rule_id
required
string <uuid>

UUID of the cache rule resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a cache rule

Authorizations:
BearerAuth
path Parameters
cache_rule_id
required
string <uuid>

UUID of the cache rule resource.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cache policies for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a cache policy for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
enabled
boolean
Default: true
priority
integer [ 0 .. 10000 ]
Default: 100
required
object (CacheRuleMatch)

Path and method conditions that activate this cache rule. At least one of paths or content_types must be provided.

ttl_seconds
required
integer >= 0
browser_ttl_seconds
integer or null >= 0
object (CacheKey)

Controls which request attributes are included in the cache key. Reducing the key cardinality increases cache hit rates but may cause stale data to be served across different users or contexts.

object (CacheBypass)

Conditions under which caching is skipped entirely.

stale_while_revalidate_seconds
integer or null >= 0
stale_if_error_seconds
integer or null >= 0
cache_status_header
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "priority": 100,
  • "match": {
    },
  • "ttl_seconds": 0,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 0,
  • "stale_if_error_seconds": 0,
  • "cache_status_header": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "name": "Static Assets Cache",
  • "enabled": true,
  • "priority": 50,
  • "match": {
    },
  • "ttl_seconds": 86400,
  • "browser_ttl_seconds": 0,
  • "cache_key": {
    },
  • "bypass": {
    },
  • "stale_while_revalidate_seconds": 60,
  • "stale_if_error_seconds": 3600,
  • "cache_status_header": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Purge

Cache purge requests and audit history

List purge requests

Returns the purge audit history, newest first.

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "pending" "in_progress" "completed" "failed"
type
string
Enum: "path" "wildcard" "tag"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Submit a cache purge

Validates and submits a purge request. Purges are executed asynchronously across edge nodes. Poll GET /purge/{purge_id} to track propagation.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "path",
  • "paths": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a purge request

Authorizations:
BearerAuth
path Parameters
purge_id
required
string <uuid>

UUID of the purge request.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List purge requests

Returns the purge audit history, newest first.

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "pending" "in_progress" "completed" "failed"
type
string
Enum: "path" "wildcard" "tag"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Submit a cache purge

Validates and submits a purge request. Purges are executed asynchronously across edge nodes. Poll GET /purge/{purge_id} to track propagation.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "path",
  • "paths": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a purge request

Authorizations:
BearerAuth
path Parameters
purge_id
required
string <uuid>

UUID of the purge request.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List purge requests for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Purge cache for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
{
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List purge requests for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Purge cache for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
{
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

AdminUsers

Admin user management

List admin users

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

role
string
Enum: "viewer" "operator" "admin" "superadmin"
status
string
Enum: "active" "deactivated"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an admin user

Creates an admin user and sends an invitation email. The invited user sets their own password via the invitation link.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
display_name
string <= 100 characters
role
required
string
Enum: "viewer" "operator" "admin" "superadmin"

Responses

Request samples

Content type
application/json
{
  • "email": "ops@encorastream.com",
  • "display_name": "Ops Engineer",
  • "role": "operator"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "role": "viewer",
  • "status": "active",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an admin user

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the admin user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "role": "viewer",
  • "status": "active",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an admin user

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the admin user.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
display_name
string <= 100 characters
role
string
Enum: "viewer" "operator" "admin" "superadmin"

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "role": "viewer",
  • "status": "active",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deactivate an admin user

Revokes the user's access immediately. All active sessions are invalidated. Deactivated users cannot log in. This action is reversible via reactivation. Superadmin accounts cannot be deactivated by non-superadmin callers.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the admin user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "role": "viewer",
  • "status": "active",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reactivate a deactivated admin user

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the admin user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "role": "viewer",
  • "status": "active",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

ApiTokens

API token issuance and rotation

List API tokens

Returns all tokens. Token values are never returned in list responses.

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "active" "revoked"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an API token

Creates a new API token. The plaintext token value is returned only in this response under the token field. It cannot be retrieved again — store it securely.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string <= 100 characters
role
required
string
Enum: "viewer" "operator" "admin"
expires_at
string <date-time>

Optional expiry timestamp. Omit for a non-expiring token.

Responses

Request samples

Content type
application/json
{
  • "name": "CI Deploy Token",
  • "role": "operator",
  • "expires_at": "2027-01-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "CI Deploy Token",
  • "role": "viewer",
  • "status": "active",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an API token

Returns token metadata. The token value is never returned.

Authorizations:
BearerAuth
path Parameters
token_id
required
string <uuid>

UUID of the API token.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "CI Deploy Token",
  • "role": "viewer",
  • "status": "active",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Revoke an API token

Permanently revokes the token. Active requests using this token are rejected immediately. This action is irreversible.

Authorizations:
BearerAuth
path Parameters
token_id
required
string <uuid>

UUID of the API token.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Rotate an API token

Atomically revokes the current token and issues a replacement with the same name, role, and expiry. The new plaintext value is returned once under token. The old token is invalidated immediately.

Authorizations:
BearerAuth
path Parameters
token_id
required
string <uuid>

UUID of the API token.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "CI Deploy Token",
  • "role": "viewer",
  • "status": "active",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

AuditLogs

Audit log access

List audit logs

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

actor_id
string <uuid>

Filter by actor UUID.

resource_type
string <= 100 characters

Filter by resource type (e.g. origin, route, cache_rule, purge).

resource_id
string <uuid>

Filter by resource UUID.

action
string <= 200 characters

Filter by action pattern (e.g. origin.created).

from
string <date-time>

Start of time range (inclusive, ISO 8601).

to
string <date-time>

End of time range (inclusive, ISO 8601).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get an audit log entry

Authorizations:
BearerAuth
path Parameters
audit_log_id
required
string <uuid>

UUID of the audit log entry.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "origin.created",
  • "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
  • "actor_type": "user",
  • "actor_role": "viewer",
  • "resource_type": "origin",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "ip_address": "203.0.113.0",
  • "user_agent": "string",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Configuration

Configuration validation, publishing, versioning, and rollback

List configuration versions

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "draft" "validating" "valid" "invalid" "publishing" "active" "superseded" "rolled_back"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a configuration version

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

UUID of the configuration version.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version_number": 42,
  • "description": "Added cache rule for /static/* assets",
  • "status": "draft",
  • "validation_errors": [
    ],
  • "propagation_status": {
    },
  • "published_by": "9ac9eee7-2153-423d-b22d-04e12679154a",
  • "published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Validate pending configuration

Runs a validation pass on the current set of origins, routes, and cache rules without publishing. Returns a new draft ConfigVersion with status valid or invalid. Useful for dry-run checks before publishing.

Authorizations:
BearerAuth
Request Body schema: application/json
optional
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version_number": 42,
  • "description": "Added cache rule for /static/* assets",
  • "status": "draft",
  • "validation_errors": [
    ],
  • "propagation_status": {
    },
  • "published_by": "9ac9eee7-2153-423d-b22d-04e12679154a",
  • "published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Publish configuration

Validates and publishes the current configuration to all edge nodes. If validation fails, the request returns 422 with validation errors and no change is made. An Idempotency-Key is recommended to avoid duplicate publishes.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
optional
description
string <= 500 characters

Optional human-readable change description for this publish.

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version_number": 42,
  • "description": "Added cache rule for /static/* assets",
  • "status": "draft",
  • "validation_errors": [
    ],
  • "propagation_status": {
    },
  • "published_by": "9ac9eee7-2153-423d-b22d-04e12679154a",
  • "published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Roll back to a previous configuration version

Rolls back to a previous superseded configuration version. The target version is re-published as a new active version. The rollback action is recorded in the audit log with the acting admin's identity.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
target_version_id
required
string <uuid>

UUID of the configuration version to roll back to. Must have status superseded.

reason
string <= 500 characters

Optional reason for rollback, recorded in the audit log.

Responses

Request samples

Content type
application/json
{
  • "target_version_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f0099",
  • "reason": "Revert route change that caused elevated error rates."
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version_number": 42,
  • "description": "Added cache rule for /static/* assets",
  • "status": "draft",
  • "validation_errors": [
    ],
  • "propagation_status": {
    },
  • "published_by": "9ac9eee7-2153-423d-b22d-04e12679154a",
  • "published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Health

Liveness, readiness, and dependency health checks

Liveness check

Returns 200 if the API process is running and able to accept requests. Intended for container orchestrator liveness probes. No authentication required.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Readiness check

Returns 200 if the service is ready to handle traffic (database and Redis are reachable). Returns 503 if any dependency is unavailable. No authentication required.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "2.0.0",
  • "timestamp": "2026-06-18T10:00:00Z",
  • "components": {
    }
}

Endpoints

CDN endpoint (distribution) management — custom hostnames, TLS, geo restrictions, and compression

List CDN endpoints

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

status
string
Enum: "deploying" "active" "disabled" "error"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a CDN endpoint

Creates a new CDN endpoint (distribution). The platform provisions a CDN-assigned hostname and begins deploying configuration to edge nodes. Status transitions to active once propagation completes.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
default_origin_id
required
string <uuid>
http_version
string
Default: "http2"
Enum: "http1.1" "http2" "http2and3"
ipv6_enabled
boolean
Default: true
response_headers_policy_id
string <uuid>
object (TlsConfig)

TLS settings applied to client-facing connections on this endpoint.

object (CompressionConfig)

Automatic response compression. The edge compresses responses if the client sends Accept-Encoding containing the configured algorithm and the response is compressible (text-based content type, no Content-Encoding already set, size ≥ min_size_bytes).

object (GeoRestriction)

Country-level access control. Uses the client IP address resolved to an ISO 3166-1 alpha-2 country code. VPN / proxy detection is not performed at this layer.

Array of objects (CustomErrorPage)
shield_region
string
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "Main Web Distribution",
  • "default_origin_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f0001",
  • "http_version": "http2and3",
  • "ipv6_enabled": true,
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a CDN endpoint

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a CDN endpoint

Partial update. Fields not sent are unchanged. Configuration changes trigger a new deployment propagation cycle (status → deploying).

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
default_origin_id
string <uuid>
http_version
string
Enum: "http1.1" "http2" "http2and3"
ipv6_enabled
boolean
response_headers_policy_id
string or null <uuid>
object (TlsConfig)

TLS settings applied to client-facing connections on this endpoint.

object (CompressionConfig)

Automatic response compression. The edge compresses responses if the client sends Accept-Encoding containing the configured algorithm and the response is compressible (text-based content type, no Content-Encoding already set, size ≥ min_size_bytes).

object (GeoRestriction)

Country-level access control. Uses the client IP address resolved to an ISO 3166-1 alpha-2 country code. VPN / proxy detection is not performed at this layer.

Array of objects (CustomErrorPage)
shield_region
string or null
tags
Array of strings[ items <= 64 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a CDN endpoint

Deletes the endpoint and deprovisions its CDN hostname. All custom domains must be removed before deletion. This action is irreversible.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Enable a CDN endpoint

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a CDN endpoint

Stops serving traffic. Configuration and custom domains are preserved.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Main Web Distribution",
  • "default_origin_id": "16367423-bbda-49b9-87cc-ee707563667e",
  • "hostname": "a1b2c3d4.cdn.encorastream.com",
  • "status": "deploying",
  • "http_version": "http1.1",
  • "ipv6_enabled": true,
  • "response_headers_policy_id": "780ee3f1-d030-47d5-8ecc-82ecc0db9acc",
  • "tls_config": {
    },
  • "compression": {
    },
  • "geo_restriction": {
    },
  • "custom_error_pages": [
    ],
  • "shield_region": "eu-west-1",
  • "tags": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Purge cache for an endpoint

Submits a targeted cache purge scoped to a single endpoint. Supports purging everything, specific URLs, path prefixes, tags, or cache rule IDs. Equivalent to POST /cache/purge but pre-scoped to one endpoint.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
type
string
Deprecated
Enum: "path" "wildcard" "tag" "all"

Backward-compatible alias for purge_type.

purge_type
required
string
Enum: "path" "wildcard" "tag" "all"
paths
Array of strings [ 1 .. 500 ] items [ items <= 2048 characters ]

Required for type path or wildcard.

tags
Array of strings [ 1 .. 100 ] items [ items <= 256 characters ]

Required for type tag.

Responses

Request samples

Content type
application/json
Example
{
  • "scope": "everything"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "distribution_id": "11d26b58-bf71-4381-aa01-44a5bc2b0662",
  • "type": "path",
  • "purge_type": "path",
  • "paths": [
    ],
  • "tags": [
    ],
  • "status": "pending",
  • "edge_nodes_total": 0,
  • "edge_nodes_completed": 0,
  • "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Prefetch URLs into edge cache

Proactively warms the edge cache by fetching up to 500 URLs from origin and storing the responses. Useful after deployments or content publishes to prevent cache-miss thundering-herd on first real user requests.

URLs must belong to the endpoint's CDN hostname or a configured custom domain.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
urls
required
Array of strings <uri> [ 1 .. 500 ] items [ items <uri > ]

Fully-qualified URLs to prefetch. Must belong to the endpoint's hostnames (CDN hostname or a configured custom domain).

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Scheduling priority relative to other pending prefetch jobs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "total": 0,
  • "fetched": 0,
  • "failed": 0,
  • "failed_urls": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Get cache prefetch job status

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

job_id
required
string <uuid>

UUID of the cache prefetch job.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "total": 0,
  • "fetched": 0,
  • "failed": 0,
  • "failed_urls": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

CustomDomains

Custom hostname attachment and TLS certificate provisioning

List custom domains for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Attach a custom domain to a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
hostname
required
string <= 253 characters

Fully qualified domain name to attach (e.g. cdn.example.com). Wildcard hostnames (*.example.com) are supported with custom certificates only.

certificate_source
required
string
Enum: "managed" "custom"
object

Required when certificate_source is custom.

Responses

Request samples

Content type
application/json
{
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "custom_certificate": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List custom domains for an endpoint

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

certificate_status
string
Enum: "pending_validation" "provisioning" "active" "expiring_soon" "expired" "failed"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add a custom domain to an endpoint

Attaches a custom hostname to the endpoint. For managed certificates, DNS validation records are returned and must be created in your DNS provider before the certificate can be provisioned. For custom certificates, the certificate chain and private key must be provided — the private key is encrypted at rest and never returned.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
hostname
required
string <= 253 characters

Fully qualified domain name to attach (e.g. cdn.example.com). Wildcard hostnames (*.example.com) are supported with custom certificates only.

certificate_source
required
string
Enum: "managed" "custom"
object

Required when certificate_source is custom.

Responses

Request samples

Content type
application/json
Example
{
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a custom domain

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

domain_id
required
string <uuid>

UUID of the custom domain.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove a custom domain from an endpoint

Detaches the custom hostname and revokes the managed certificate if applicable. Requests to this hostname will no longer be served after propagation completes.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

domain_id
required
string <uuid>

UUID of the custom domain.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Retry certificate validation

Triggers a re-attempt of DNS validation and certificate provisioning for a managed certificate. Use when the initial validation failed or DNS records were added after the domain was created. No-op if certificate is already active.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

domain_id
required
string <uuid>

UUID of the custom domain.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace certificate on a custom domain

Replaces the TLS certificate for a domain that uses a custom certificate. Use for manual certificate renewals. The new certificate is deployed to all edge nodes without downtime using a grace period overlap.

The private key is encrypted at rest (AES-256-GCM) and never returned in any response.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

domain_id
required
string <uuid>

UUID of the custom domain.

Request Body schema: application/json
required
certificate_pem
required
string

Full PEM-encoded certificate chain (leaf + intermediates). Must match the domain hostname.

private_key_pem
required
string

PEM-encoded private key corresponding to the certificate.

Responses

Request samples

Content type
application/json
{
  • "certificate_pem": "string",
  • "private_key_pem": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "hostname": "cdn.example.com",
  • "certificate_source": "managed",
  • "certificate_status": "pending_validation",
  • "certificate_expires_at": "2019-08-24T14:15:22Z",
  • "dns_validation": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

ResponseHeadersPolicies

Reusable policies for CORS, security headers, and custom request/response headers

List response headers policies for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a response headers policy for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
description
string <= 500 characters
object (CorsConfig)

Cross-Origin Resource Sharing policy applied to matched responses. When enabled, the CDN injects or overrides CORS headers on behalf of the origin. Requests with an Origin header not matching allow_origins receive no CORS headers.

object (SecurityHeadersConfig)

OWASP-recommended security response headers. Each header can be individually enabled and optionally set to override the origin value (default) or only fill when absent.

Array of objects (CustomHeaderEntry)
remove_response_headers
Array of strings[ items <= 256 characters ]
Array of objects (CustomHeaderEntry)
remove_request_headers
Array of strings[ items <= 256 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard Security Headers",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List response headers policies

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

sort
string

Sort field and direction. Prefix with - for descending. Example: sort=-created_at

q
string <= 200 characters

Full-text search query (max 200 characters).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a response headers policy

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
description
string <= 500 characters
object (CorsConfig)

Cross-Origin Resource Sharing policy applied to matched responses. When enabled, the CDN injects or overrides CORS headers on behalf of the origin. Requests with an Origin header not matching allow_origins receive no CORS headers.

object (SecurityHeadersConfig)

OWASP-recommended security response headers. Each header can be individually enabled and optionally set to override the origin value (default) or only fill when absent.

Array of objects (CustomHeaderEntry)
remove_response_headers
Array of strings[ items <= 256 characters ]
Array of objects (CustomHeaderEntry)
remove_request_headers
Array of strings[ items <= 256 characters ]

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Standard Security Headers",
  • "description": "OWASP-recommended headers for all public endpoints",
  • "security_headers": {
    },
  • "remove_response_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard Security Headers",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a response headers policy

Authorizations:
BearerAuth
path Parameters
policy_id
required
string <uuid>

UUID of the response headers policy.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard Security Headers",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a response headers policy

Partial update. Changes take effect on the next request after propagation. All endpoints and routes referencing this policy pick up the update automatically.

Authorizations:
BearerAuth
path Parameters
policy_id
required
string <uuid>

UUID of the response headers policy.

header Parameters
If-Match
string

ETag of the resource version the client last read. The request is rejected with 412 Precondition Failed if the resource has changed since, preventing lost updates. Recommended on all admin mutations.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
description
string <= 500 characters
object (CorsConfig)

Cross-Origin Resource Sharing policy applied to matched responses. When enabled, the CDN injects or overrides CORS headers on behalf of the origin. Requests with an Origin header not matching allow_origins receive no CORS headers.

object (SecurityHeadersConfig)

OWASP-recommended security response headers. Each header can be individually enabled and optionally set to override the origin value (default) or only fill when absent.

Array of objects (CustomHeaderEntry)
remove_response_headers
Array of strings[ items <= 256 characters ]
Array of objects (CustomHeaderEntry)
remove_request_headers
Array of strings[ items <= 256 characters ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Standard Security Headers",
  • "description": "string",
  • "cors": {
    },
  • "security_headers": {
    },
  • "custom_response_headers": [
    ],
  • "remove_response_headers": [
    ],
  • "custom_request_headers": [
    ],
  • "remove_request_headers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a response headers policy

Deletes the policy. Fails with 409 Conflict if the policy is currently referenced by one or more endpoints or routes.

Authorizations:
BearerAuth
path Parameters
policy_id
required
string <uuid>

UUID of the response headers policy.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

SigningKeys

HMAC signing keys for generating and validating signed URLs (private content delivery)

List signing keys for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a signing key for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
algorithm
string
Default: "HMAC-SHA256"
Enum: "HMAC-SHA256" "HMAC-SHA512"
secret
string >= 32 characters

Custom secret value. If omitted, the server generates a cryptographically secure 64-character secret automatically.

token_param
string
Default: "token"
expires_param
string
Default: "expires"
ip_binding_enabled
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "algorithm": "HMAC-SHA256",
  • "secret": "stringstringstringstringstringst",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production signing key",
  • "algorithm": "HMAC-SHA256",
  • "status": "active",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List signing keys for an endpoint

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a signing key

Creates a new HMAC signing key for this endpoint. The secret is returned once only in the response — store it securely. Subsequent reads omit the secret.

When multiple active keys exist, the CDN validates tokens signed with any of them, enabling zero-downtime key rotation.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
algorithm
string
Default: "HMAC-SHA256"
Enum: "HMAC-SHA256" "HMAC-SHA512"
secret
string >= 32 characters

Custom secret value. If omitted, the server generates a cryptographically secure 64-character secret automatically.

token_param
string
Default: "token"
expires_param
string
Default: "expires"
ip_binding_enabled
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Primary signing key",
  • "algorithm": "HMAC-SHA256"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production signing key",
  • "algorithm": "HMAC-SHA256",
  • "secret": "string",
  • "status": "active",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a signing key

Returns signing key metadata. The secret is never returned.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

key_id
required
string <uuid>

UUID of the signing key.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production signing key",
  • "algorithm": "HMAC-SHA256",
  • "status": "active",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a signing key

Permanently deletes the signing key. Any signed URLs generated with this key will immediately become invalid. Ensure the key is no longer in use before deletion. Cannot delete the last active signing key if token auth is enabled.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

key_id
required
string <uuid>

UUID of the signing key.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Rotate a signing key

Generates a new secret for an existing signing key. During the rotation grace period (default 24 hours), the CDN accepts tokens signed with either the old or new secret, enabling zero-downtime rotation. The new secret is returned once only.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

key_id
required
string <uuid>

UUID of the signing key.

Request Body schema: application/json
grace_period_hours
integer [ 0 .. 168 ]
Default: 24

How long (in hours) the old secret remains valid after rotation. Set to 0 for immediate invalidation.

Responses

Request samples

Content type
application/json
{
  • "grace_period_hours": 24
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production signing key",
  • "algorithm": "HMAC-SHA256",
  • "secret": "string",
  • "status": "active",
  • "token_param": "token",
  • "expires_param": "expires",
  • "ip_binding_enabled": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

IpAccessRules

Per-endpoint IP allow/block rules for edge-level access control

List IP access rules for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an IP access rule for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "block" "challenge"
cidr
required
string
description
string <= 255 characters
priority
integer [ 1 .. 1000 ]
Default: 100

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "cidr": "string",
  • "description": "string",
  • "priority": 100
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "allow",
  • "cidr": "203.0.113.0/24",
  • "description": "string",
  • "priority": 100,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List IP access rules for an endpoint

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

action
string
Enum: "allow" "block" "challenge"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an IP access rule

Adds an allow or block rule for a CIDR range. Rules are evaluated at the edge before any cache lookup or origin request. Lower priority values are evaluated first.

Caution: Adding a block rule without any allow rules blocks all non-matching traffic by default only if a default-deny policy is configured on the endpoint.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "block" "challenge"
cidr
required
string
description
string <= 255 characters
priority
integer [ 1 .. 1000 ]
Default: 100

Responses

Request samples

Content type
application/json
Example
{
  • "action": "block",
  • "cidr": "192.0.2.0/24",
  • "description": "Block known scraper range",
  • "priority": 10
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "allow",
  • "cidr": "203.0.113.0/24",
  • "description": "string",
  • "priority": 100,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an IP access rule

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

rule_id
required
string <uuid>

UUID of the IP access rule.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "allow",
  • "cidr": "203.0.113.0/24",
  • "description": "string",
  • "priority": 100,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an IP access rule

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

rule_id
required
string <uuid>

UUID of the IP access rule.

Request Body schema: application/json
required
non-empty
action
string
Enum: "allow" "block" "challenge"
description
string or null <= 255 characters
priority
integer [ 1 .. 1000 ]

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "description": "string",
  • "priority": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "action": "allow",
  • "cidr": "203.0.113.0/24",
  • "description": "string",
  • "priority": 100,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an IP access rule

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the CDN endpoint.

rule_id
required
string <uuid>

UUID of the IP access rule.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

LogDrains

Ship CDN access logs to external destinations (S3, Datadog, Elasticsearch, HTTP)

List log drains for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a log drain for a distribution

Authorizations:
BearerAuth
path Parameters
distribution_id
required
string <uuid>

UUID of the CDN distribution. Distribution is an alias of CDN endpoint.

Request Body schema: application/json
required
name
required
string <= 100 characters
destination_type
required
string
Enum: "s3" "datadog" "elasticsearch" "http" "gcs"
destination_config
required
object
log_format
string
Default: "ndjson"
Enum: "json" "ndjson" "w3c_extended"
fields
Array of strings
endpoint_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "destination_type": "s3",
  • "destination_config": { },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List log drains

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "active" "paused" "error"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a log drain

Creates a new log drain that ships CDN access logs to an external destination. After creation, use POST /log-drains/{drain_id}/test to verify connectivity before enabling in production.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters

Client-generated unique key (UUIDv7 recommended) that makes a write request safely retryable. Replaying the same key within 24 h returns the original result instead of performing the action twice. Recommended on purge and configuration publish requests.

Request Body schema: application/json
required
name
required
string <= 100 characters
destination_type
required
string
Enum: "s3" "datadog" "elasticsearch" "http" "gcs"
destination_config
required
object
log_format
string
Default: "ndjson"
Enum: "json" "ndjson" "w3c_extended"
fields
Array of strings
endpoint_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Production logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "ndjson"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a log drain

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a log drain

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Request Body schema: application/json
required
non-empty
name
string <= 100 characters
destination_config
object
log_format
string
Enum: "json" "ndjson" "w3c_extended"
fields
Array of strings
endpoint_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "destination_config": { },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a log drain

Stops log delivery and removes the drain configuration.

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Test log drain connectivity

Sends a synthetic test log event to the destination to verify credentials and connectivity. Returns the result synchronously. Does not affect production log delivery.

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "latency_ms": 0,
  • "error": "string"
}

Pause a log drain

Suspends log delivery without deleting the drain configuration.

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Resume a log drain

Resumes log delivery for a paused drain.

Authorizations:
BearerAuth
path Parameters
drain_id
required
string <uuid>

UUID of the log drain.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Production access logs → S3",
  • "destination_type": "s3",
  • "destination_config": {
    },
  • "log_format": "json",
  • "fields": [
    ],
  • "endpoint_ids": [
    ],
  • "status": "active",
  • "last_error": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Observability

Metrics, bandwidth analytics, geographic distribution, top URLs, and edge node status

List edge nodes

Returns the current status and config sync state of all edge nodes.

Authorizations:
BearerAuth
query Parameters
cursor
string

Opaque pagination cursor from meta.next_cursor.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1–100, default 20).

status
string
Enum: "online" "offline" "draining"
region
string

Filter by region identifier.

config_synced
boolean

Filter nodes by config sync state.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get request statistics

Aggregated request metrics across all edge nodes for the specified period.

Authorizations:
BearerAuth
query Parameters
period
required
string
Enum: "last_1h" "last_6h" "last_24h" "last_7d"
origin_id
string <uuid>

Scope statistics to a specific origin.

Responses

Response samples

Content type
application/json
{
  • "period": "last_1h",
  • "total_requests": 0,
  • "cache_hit_rate": 1,
  • "error_rate": 1,
  • "avg_response_time_ms": 0.1,
  • "p95_response_time_ms": 0.1,
  • "p99_response_time_ms": 0.1,
  • "bytes_served": 0,
  • "by_status_class": {
    }
}

Get cache statistics

Aggregated cache hit/miss metrics for the specified period.

Authorizations:
BearerAuth
query Parameters
period
required
string
Enum: "last_1h" "last_6h" "last_24h" "last_7d"
cache_rule_id
string <uuid>

Scope statistics to a specific cache rule.

Responses

Response samples

Content type
application/json
{
  • "period": "last_1h",
  • "hit_count": 0,
  • "miss_count": 0,
  • "bypass_count": 0,
  • "revalidate_count": 0,
  • "stale_count": 0,
  • "hit_rate": 1,
  • "bytes_from_cache": 0,
  • "bytes_from_origin": 0
}

List available origin shield regions

Returns all available origin shield (mid-tier cache) regions and their current availability status. Use the id field as shield_region in EndpointCreate or EndpointUpdate.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get bandwidth usage statistics

Returns egress bandwidth metrics including total bytes transferred, cache vs origin breakdown, and a per-interval timeseries for chart rendering.

Authorizations:
BearerAuth
query Parameters
period
required
string
Enum: "last_1h" "last_6h" "last_24h" "last_7d" "last_30d"
endpoint_id
string <uuid>

Scope to a specific endpoint. Omit for all endpoints.

granularity
string
Enum: "1m" "5m" "15m" "1h" "6h" "1d"

Timeseries bucket size. Defaults to a sensible value per period (e.g. 5m for last_1h, 1h for last_24h).

Responses

Response samples

Content type
application/json
{
  • "period": "last_24h",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "total_bytes_transferred": 0,
  • "total_bytes_from_cache": 0,
  • "total_bytes_from_origin": 0,
  • "cache_bandwidth_ratio": 1,
  • "timeseries": [
    ]
}

Get top requested URLs

Returns the most-requested URLs for the specified period, ranked by request count or bytes transferred. Useful for identifying cache candidates and traffic hotspots.

Authorizations:
BearerAuth
query Parameters
period
required
string
Enum: "last_1h" "last_6h" "last_24h" "last_7d"
endpoint_id
string <uuid>
ranked_by
string
Default: "requests"
Enum: "requests" "bytes_transferred"
limit
integer [ 1 .. 500 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "period": "string",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "ranked_by": "requests",
  • "items": [
    ]
}

Get geographic traffic distribution

Returns request and bandwidth metrics broken down by country and continent. Useful for geo restriction tuning, capacity planning, and compliance reporting.

Authorizations:
BearerAuth
query Parameters
period
required
string
Enum: "last_1h" "last_6h" "last_24h" "last_7d" "last_30d"
endpoint_id
string <uuid>
limit
integer [ 1 .. 250 ]
Default: 100

Maximum number of countries to return (ranked by request volume).

Responses

Response samples

Content type
application/json
{
  • "period": "string",
  • "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
  • "by_country": [
    ],
  • "by_continent": [
    ]
}