Endpoints

Read the callable paths an application exposes on its active version.

Introduction

Endpoints are read-only here, because they come from your source rather than from an API call. A code app derives them from the methods you decorated, and a container app declares them in its container.yaml.

A path is one or more lowercase segments joined by slashes, with no leading slash, such as generate or v1/chat/completions. Each segment is up to 64 characters, the whole path up to 255, and an app serves at most 20 of them. What this page reports is the set on the app's active version, which is what a request can actually reach today.

default: true marks the endpoint a root invocation reaches: the one the app marks as its default, or its only endpoint when it has exactly one. The field is omitted on every other endpoint.

List endpoints

GETapi.serverless.runware.ai/v1/apps/{appId}/endpoints

Lists the endpoints of the app's active version. The set is written by the source itself, a code build's introspection, or a container's config document, and is replaced atomically whenever a version activates, so a deploy of a newer version or a rollback to an older one is immediately reflected here. Empty while the app is initializing: nothing is routable until its first build is ready and deployed. Pass path to resolve one endpoint by the name invocation uses, instead of paging the set. The response is that one endpoint, or 404 when the live app does not declare it. id on it is the UUID metrics and events use. path together with cursor is 422: a path names one row, not a position in a page. Each row may include runtime (status, req/min, p95, p99) from the latest 5-minute Insights window. Those fields are omitted when metrics cannot be read or the endpoint has no samples. Identity always comes from Postgres.

Request

Path

appId stringrequiredmin: 6max: 30: Immutable app identifier, unique among the authenticated organization's live apps in one environment. The environment query parameter selects which copy the request addresses.

Query

environment stringmin: 1max: 63: The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: appId together with environment selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means production. A name the organization has no live environment under returns 404.

limit integerint32min: 1max: 100default: 20: Maximum number of items to return.

cursor string: Opaque pagination cursor returned by a previous call, as nextCursor or, on the operations that offer one, prevCursor.

path stringmin: 1max: 255: Resolve this one endpoint by its invocation path, instead of paging the set. The response is that endpoint, or 404 when the live app does not declare it. Cannot be combined with cursor.

Response

nextCursor stringnullable: Cursor for the next page. Null when there are no more items.

data object[]

Array items7 properties each

id string (uuid)requiredUUID v4: Allocated row identifier. getEndpoint, AppEvent.endpointId, and the metrics endpoint and endpointId filters use this UUID. A path that is removed and added again is a new row, so this id does not follow the name. GET /v1/apps/{appId}/endpoints/{endpointId} resolves it back to path.

appId stringrequiredmin: 6max: 30: Immutable app identifier. Unique among the authenticated organization's live apps in one environment: it cannot be changed after creation, it becomes available again once the app it named reaches deleted, and the same id may run once in each environment as a separate copy.

path stringrequired: The customer-authored name invocation and Task.endpointPath use: one or more bare lowercase segments joined by slashes, such as generate or v1/chat/completions, with no leading or trailing slash. Unique within the app. It is not the metrics or events key: that is id. GET /v1/apps/{appId}/endpoints?path= resolves this name to id.

default boolean: True when this endpoint is the one a root invocation addresses: the endpoint the app marks as its default (@endpoint(default=True), or default: true in a container.yaml at configVersion: 2), or its only endpoint when it has exactly one. Omitted when it is not. An app marks one endpoint at most.

createdAt string (date-time)date-time

updatedAt string (date-time)date-time

runtime object

Latest-window traffic for one endpoint. Identity stays on the parent Endpoint. These fields come from Insights and are omitted independently when their backing series has no samples. The whole object is omitted when Insights is unset, times out, or the endpoint had no request samples. Zero is a reading, not an absence.

Properties4 properties

status string: Badge derived from the latest-window error ratio (4xx + 5xx over requests). Not stored: there is no endpoint status column. Omitted when metrics cannot be read or the endpoint had no requests in the window. healthy is a zero ratio, degraded is below 0.05, unhealthy is 0.05 and above.
Possible values3 values

requestsPerMinute numberdoublemin: 0: 5-minute request rate (rate(rw_requests_total[5m]) * 60), in req/min. Not derived from the 24h sparkline counts.

p95RequestDuration numberdoublemin: 0: Latest-window p95 request duration in seconds (all requests, the duration histogram has no status class).

p99RequestDuration numberdoublemin: 0: Latest-window p99 request duration in seconds (all requests, the duration histogram has no status class).

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`422`	The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

Get an endpoint

GETapi.serverless.runware.ai/v1/apps/{appId}/endpoints/{endpointId}

Returns one live endpoint on the app. runtime is the same optional latest-window traffic as listEndpoints and is omitted when metrics cannot be read or the endpoint has no samples.