Unleash Unleash Edge API
Endpoints related to [Unleash Edge](https://docs.getunleash.io/unleash-edge).
OpenAPI Specification
openapi: 3.0.3
info:
title: Unleash Admin Addons Unleash Edge API
version: 7.4.1
description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Unleash Edge
description: Endpoints related to [Unleash Edge](https://docs.getunleash.io/unleash-edge).
paths:
/api/client/metrics/edge:
post:
summary: Register Edge Observability Metrics.
description: '**Enterprise feature**
Registers Edge observability metrics from downstream Edge instances to aggregate a comprehensive status view of connected Edges.'
tags:
- Unleash Edge
operationId: registerEdgeObservabilityMetrics
requestBody:
description: edgeInstanceDataSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/edgeInstanceDataSchema'
responses:
'202':
description: This response has no body.
/api/client/metrics/bulk:
post:
tags:
- Unleash Edge
summary: Send Metrics in Bulk
description: This operation accepts batched metrics from any client. Metrics will be inserted into Unleash's metrics storage
operationId: clientBulkMetrics
requestBody:
description: bulkMetricsSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/bulkMetricsSchema'
responses:
'202':
description: This response has no body.
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'413':
description: The request body is larger than what we accept. By default we only accept bodies of 100kB or less
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTooLarge
description: The name of the error kind
message:
type: string
example: You provided more data than we can handle. Unleash accepts at most X MB.
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
/edge/validate:
post:
tags:
- Unleash Edge
security:
- {}
summary: Check Which Tokens Are Valid
description: This operation accepts a list of tokens to validate. Unleash will validate each token you provide. For each valid token you provide, Unleash will return the token along with its type and which projects it has access to.
operationId: getValidTokens
requestBody:
description: tokenStringListSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tokenStringListSchema'
responses:
'200':
description: validatedEdgeTokensSchema
content:
application/json:
schema:
$ref: '#/components/schemas/validatedEdgeTokensSchema'
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'413':
description: The request body is larger than what we accept. By default we only accept bodies of 100kB or less
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTooLarge
description: The name of the error kind
message:
type: string
example: You provided more data than we can handle. Unleash accepts at most X MB.
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
components:
schemas:
edgeLatencyMetricsSchema:
description: Representing latency for an Edge operation.
type: object
additionalProperties: false
required:
- avg
- count
- p99
properties:
avg:
type: number
description: Average time per request in milliseconds.
minimum: 0
count:
type: number
description: Total number of requests made.
minimum: 0
p99:
type: number
description: 99% of requests finished within this amount of milliseconds.
minimum: 0
example: 34.5
bulkMetricsSchema:
type: object
required:
- applications
- metrics
description: A batch of metrics accumulated by Edge (or other compatible applications). Includes both application registrations as well usage metrics from clients
properties:
applications:
description: A list of applications registered by an Unleash SDK
type: array
items:
$ref: '#/components/schemas/bulkRegistrationSchema'
metrics:
description: a list of client usage metrics registered by downstream providers. (Typically Unleash Edge)
type: array
items:
$ref: '#/components/schemas/clientMetricsEnvSchema'
impactMetrics:
description: a list of custom impact metrics registered by downstream providers. (Typically Unleash Edge)
type: array
items:
$ref: '#/components/schemas/impactMetricsSchema'
impactMetricsSchema:
type: object
description: Used for reporting impact metrics from SDKs
oneOf:
- required:
- name
- help
- type
- samples
properties:
name:
type: string
description: Name of the impact metric
example: my-counter
help:
description: Human-readable description of what the metric measures
type: string
example: Counts the number of operations
type:
description: Type of the metric
type: string
enum:
- counter
- gauge
example: counter
samples:
description: Samples of the numeric metric
type: array
items:
type: object
required:
- value
description: A sample of a numeric metric with a value and optional labels
properties:
value:
type: number
description: The value of the metric sample
example: 10
labels:
description: Optional labels for the metric sample
type: object
additionalProperties:
oneOf:
- type: string
- type: number
example:
application: my-app
environment: production
- required:
- name
- help
- type
- samples
properties:
name:
type: string
description: Name of the impact metric
example: my-histogram
help:
description: Human-readable description of what the metric measures
type: string
example: Measures request duration
type:
description: Type of the metric
type: string
enum:
- histogram
example: histogram
samples:
description: Samples of the histogram metric
type: array
items:
type: object
required:
- count
- sum
- buckets
description: A sample of a histogram metric with count, sum, buckets and optional labels
properties:
count:
type: number
description: Total count of observations
example: 100
sum:
type: number
description: Sum of all observed values
example: 1500
buckets:
type: array
description: Histogram buckets
items:
type: object
required:
- le
- count
properties:
le:
oneOf:
- type: number
- type: string
enum:
- +Inf
description: Upper bound of the bucket
example: 0.5
count:
type: number
description: Count of observations in this bucket
example: 30
labels:
description: Optional labels for the metric sample
type: object
additionalProperties:
oneOf:
- type: string
- type: number
example:
application: my-app
environment: production
edgeTokenSchema:
type: object
additionalProperties: false
required:
- token
- projects
- type
description: A representation of a client token, limiting access to [CLIENT](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#backend-tokens) (used by serverside SDKs) or [FRONTEND](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#frontend-tokens) (used by proxy SDKs)
properties:
projects:
description: The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [`*`]
type: array
items:
type: string
example:
- developerexperience
- enterprisegrowth
type:
description: The [API token](https://docs.getunleash.io/concepts/api-tokens-and-client-keys)'s **type**. Unleash supports three different types of API tokens ([ADMIN](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#admin-tokens), [CLIENT](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#backend-tokens), [FRONTEND](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#frontend-tokens)). They all have varying access, so when validating a token it's important to know what kind you're dealing with
type: string
enum:
- client
- admin
- frontend
- backend
example: client
token:
description: The actual token value. [Unleash API tokens](https://docs.getunleash.io/concepts/api-tokens-and-client-keys) are comprised of three parts. <project(s)>:<environment>.randomcharacters
type: string
example: '*:development.5c806b5320c88cf27e81f3e9b97dab298a77d5879316e3c2d806206b'
dateSchema:
description: A representation of a date. Either as a date-time string or as a UNIX timestamp.
oneOf:
- type: string
format: date-time
description: An [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339.html)-compliant timestamp.
example: '2023-07-27T11:23:44Z'
- type: integer
description: A [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time).
example: 1690449593
consumptionDataPointSchema:
type: object
required:
- interval
- requests
properties:
interval:
type: array
items:
type: integer
minItems: 2
maxItems: 2
description: Time interval in milliseconds [start, end].
example:
- 0
- 15000
requests:
type: number
description: Number of requests in this interval
clientMetricsEnvSchema:
type: object
required:
- featureName
- appName
- environment
description: Used for reporting feature evaluation results from SDKs
properties:
featureName:
type: string
description: Name of the feature checked by the SDK
example: my.special.feature
appName:
description: The name of the application the SDK is being used in
type: string
example: accounting
environment:
description: Which environment the SDK is being used in
type: string
example: development
timestamp:
description: The start of the time window these metrics are valid for. The window is 1 hour wide
example: '1926-05-08T12:00:00.000Z'
$ref: '#/components/schemas/dateSchema'
'yes':
description: How many times the toggle evaluated to true
type: integer
example: 974
minimum: 0
'no':
description: How many times the toggle evaluated to false
type: integer
example: 50
minimum: 0
variants:
description: How many times each variant was returned
type: object
additionalProperties:
type: integer
minimum: 0
example:
variantA: 15
variantB: 25
variantC: 5
edgeInstanceDataSchema:
description: Represents Edge instance observability data.
type: object
required:
- identifier
- appName
- edgeVersion
- started
- traffic
- latencyUpstream
- connectedStreamingClients
- connectedEdges
properties:
identifier:
type: string
description: The ID of the Edge process, typically a ULID. Newly generated for each restart of the instance.
example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
appName:
type: string
description: The name of the application, configured by the user, typically persistent across restarts of Edge.
example: unleash-edge-us-east-1
region:
type: string
nullable: true
description: Which region the Edge instance is running in. Set to AWS_REGION by default (if present).
example: us-east-1
edgeVersion:
type: string
description: Which version (semver) of Edge is the Edge instance running.
example: 19.6.3
processMetrics:
type: object
$ref: '#/components/schemas/edgeProcessMetricsSchema'
nullable: true
started:
type: string
format: date-time
description: RFC3339 timestamp for when the Edge instance was started.
traffic:
type: object
$ref: '#/components/schemas/edgeInstanceTrafficSchema'
latencyUpstream:
type: object
$ref: '#/components/schemas/edgeUpstreamLatencySchema'
connectedStreamingClients:
type: number
minimum: 0
description: How many streaming clients are connected to the Edge instance.
connectedEdges:
type: array
description: A list of Edge instances connected to the Edge instance.
items:
$ref: '#/components/schemas/edgeInstanceDataSchema'
requestsSinceLastReport:
type: object
description: Requests made to edge's endpoints since last report. Meant to be used for billing purposes.
$ref: '#/components/schemas/edgeRequestStatsSchema'
connectionConsumptionSinceLastReport:
type: object
description: Connection consumption data since last report, including features and metrics consumption. Used for long-lived backend SDKs with backend controlled number of instances.
$ref: '#/components/schemas/connectionConsumptionSchema'
requestConsumptionSinceLastReport:
type: array
description: Request consumption data since last report, grouped by metered group. Used for frontend SDKs with unpredictable and potentially large number of user devices running those SDKs.
$ref: '#/components/schemas/requestConsumptionSchema'
hosting:
type: string
enum:
- hosted
- self-hosted
- enterprise-self-hosted
description: A marker that tells Unleash whether this Edge instance is self-hosted, enterprise self-hosted, or hosted by Unleash.
apiKeyRevisionIds:
type: array
description: List of API keys (represented by their environment and projects) and revision ids to make it easier to track sync state of edge
items:
$ref: '#/components/schemas/edgeApiKeyRevisionIdSchema'
nullable: true
bulkRegistrationSchema:
type: object
required:
- appName
- instanceId
- environment
description: An application registration. Defines the format POSTed by our backend SDKs when they're starting up
properties:
connectVia:
type: array
description: "A list of applications this app registration has been registered through. If connected directly to Unleash, this is an empty list. \n This can be used in later visualizations to tell how many levels of proxy or Edge instances our SDKs have connected through"
items:
type: object
required:
- appName
- instanceId
properties:
appName:
type: string
instanceId:
type: string
example:
- appName: unleash-edge
instanceId: edge-pod-bghzv5
appName:
description: The name of the application that is evaluating toggles
type: string
example: Ingress load balancer
environment:
description: Which environment the application is running in
type: string
example: development
instanceId:
description: A [(somewhat) unique identifier](https://docs.getunleash.io/sdks/node#advanced-usage) for the application
type: string
example: application-name-dacb1234
interval:
description: How often (in seconds) the application refreshes its features
type: number
example: 10
started:
description: The application started at
example: '1952-03-11T12:00:00.000Z'
$ref: '#/components/schemas/dateSchema'
strategies:
description: Enabled [strategies](https://docs.getunleash.io/concepts/activation-strategies) in the application
type: array
example:
- standard
- gradualRollout
items:
type: string
projects:
description: The list of projects used in the application
type: array
example:
- projectA
- projectB
items:
type: string
sdkVersion:
description: The version the sdk is running. Typically <client>:<version>
example: unleash-client-java:8.0.0
type: string
sdkType:
description: The sdk type
example: backend
type: string
enum:
- frontend
- backend
- null
nullable: true
edgeApiKeyRevisionIdSchema:
description: Represents Edge sync state of api keys
type: object
required:
- environment
- projects
- revisionId
properties:
environment:
description: The Unleash Environment this apiKey is synced for
type: string
projects:
type: array
description: The list of projects this key is valid for or * if valid for all projects
items:
type: string
revisionId:
description: The revision id of Edge's last successful sync of this key
type: number
minimum: 0
lastUpdated:
description: The timestamp of the last successful sync of this key
type: string
format: date-time
meteredGroupConsumptionSchema:
type: object
required:
- meteredGroup
- dataPoints
properties:
meteredGroup:
type: string
description: Name of the metered group
example: default
dataPoints:
type: array
items:
$ref: '#/components/schemas/consumptionDataPointSchema'
description: Array of consumption data points
edgeUpstreamLatencySchema:
description: Latencies for upstream actions from Edge (downloading/syncing new features, uploading metrics, uploading instance data)
type: object
additionalProperties: false
required:
- features
- metrics
- edge
properties:
features:
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
metrics:
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
edge:
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
tokenStringListSchema:
type: object
description: A list of unleash tokens to validate against known tokens
required:
- tokens
properties:
tokens:
description: Tokens that we want to get access information about
type: array
items:
type: string
example:
- aproject:development.randomstring
- '[]:production.randomstring'
edgeEndpointTrafficSchema:
type: object
description: Represents traffic data for a single endpoint in Edge
additionalProperties: false
properties:
requests200:
description: Number of 20x requests
type: number
minimum: 0
requests304:
description: Number of 30x requests
type: number
minimum: 0
edgeProcessMetricsSchema:
description: Represents Edge instance resource usage data.
type: object
required:
- cpuUsage
- memoryUsage
properties:
cpuUsage:
type: number
description: CPU usage, in seconds, since start of process.
minimum: 0
example: 54.54
memoryUsage:
type: number
description: Current process_resident_memory (in bytes) usage.
minimum: 0
example: 34000432
validatedEdgeTokensSchema:
type: object
additionalProperties: false
required:
- tokens
description: A object containing a list of valid Unleash tokens.
properties:
tokens:
description: The list of Unleash token objects. Each object contains the token itself and some additional metadata.
type: array
items:
$ref: '#/components/schemas/edgeTokenSchema'
edgeInstanceTrafficSchema:
description: Represents requests to the Edge instance (/api/client/features, /api/frontend, etc.)
type: object
additionalProperties: false
required:
- get
- post
- accessDenied
- cachedResponses
properties:
get:
type: object
description: A map containing GET requests.
additionalProperties:
type: object
nullable: true
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
post:
type: object
description: A map containing POST requests.
additionalProperties:
type: object
nullable: true
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
accessDenied:
type: object
description: A map containing requests that were denied.
additionalProperties:
type: object
nullable: true
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
cachedResponses:
type: object
description: A map containing requests that had cached responses.
additionalProperties:
type: object
nullable: true
$ref: '#/components/schemas/edgeLatencyMetricsSchema'
requestConsumptionSchema:
type: array
items:
type: object
required:
- meteredGroup
- requests
properties:
meteredGroup:
type: string
description: Name of the metered group
example: default
requests:
type: number
description: Total number of requests for this metered group
example: 10000
connectionConsumptionSchema:
type: object
required:
- features
- metrics
properties:
features:
type: array
items:
$ref: '#/components/schemas/meteredGroupConsumptionSchema'
description: Feature consumption data points
metrics:
type: array
items:
$ref: '#/components/schemas/meteredGroupConsumptionSchema'
description: Metrics consumption data points
edgeRequestStatsSchema:
description: Represents Edge traffic data.
type: object
properties:
/api/client/features:
description: 20x and 30x requests to the client features endpoint
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
/api/frontend:
description: Traffic to the frontend endpoint
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
/api/proxy:
description: Traffic to the proxy endpoint (proxy endpoint is deprecated, use /api/frontend instead)
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
/api/client/metrics:
description: Traffic to Edge Metrics (from SDKs)
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
/api/client/metrics/bulk:
description: Traffic to Edge Metrics (from other Edge instances)
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
/api/client/metrics/edge:
description: Traffic to Edge Metrics (from other Edge instances)
type: object
$ref: '#/components/schemas/edgeEndpointTrafficSchema'
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: API key needed to access this API
bearerToken:
type: http
scheme: bearer
description: API key needed to access this API, in Bearer token format