xCloud
declare_upstream
Declare an external API that the application calls with a stored key, or revise its declaration. Store the key first with `store_secret` and name it here; the application then calls the API through the platform's proxy at `/egress/v0/<upstream>/<path>`, and the proxy adds the key at its own edge. The proxy never gives the key to the application, though an upstream that echoes the key returns it. A key is declared here where you may edit the client to read its base URL and key from settings, and bound in the manifest's `settings` only where its host is fixed in code you must not change. With `sdk_settings`, a provider's SDK reaches the API from a deployed container with no code change. Each deploy, promote, and `restart_application` sets `base_url`'s setting to the proxy's address for this upstream, and `key`'s setting to an egress key: a credential the platform mints for this upstream and container, which the proxy swaps for the stored key. The OpenAI SDKs read `OPENAI_BASE_URL` and `OPENAI_API_KEY`; the Anthropic SDKs read `ANTHROPIC_BASE_URL` and their bearer setting, `ANTHROPIC_AUTH_TOKEN`. Nothing at the declaration, the manifest's submission, or the deploy checks that the application's client calls through the proxy, since that depends on its code, which the platform does not read. After the first call, `read_logs` with `filter: "undeclared"` and `source: "egress"`, then with `source: "harness"`, shows a call the client made to the provider's host itself. Such a call skipped `/egress/v0/`, and a failed attempt shows too. `read_status`'s `application.egress` lists the undeclared hosts the serving version reached where its `read` is `logs`, failed attempts left out, and names this upstream in `upstreams` beside its host. A host the manifest's `egress` lists shows in neither. The rest is on the page /cloud/reference/actions/declare-upstream/, which `read_documentation` reads as `page` and the platform's origin serves.
Remote (network-hosted)
Other tools also called declare_upstream?
See providers with this name
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "A name for this upstream, unique within the account; it is the `<upstream>` segment of the proxy path. Declaring it again updates the entry; its application binding cannot be unbound or rebound. An upstream the application's manifest names in `upstreams` is the manifest's, and a change to it is refused `manifest_owned_field`."
},
"base_url": {
"type": "string",
"maxLength": 2000,
"minLength": 9,
"description": "The upstream's base URL, `https://…`; calls under it are what the key is applied to."
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Deprecated: the former name of `sdk_settings`, taken as it. Send `sdk_settings`; a request naming both is refused `invalid_request`."
},
"application": {
"type": "string",
"description": "Required: the id of the one application of the acting account the upstream binds to. Every credential that reaches this action is the account’s own, so the member is always required here; refused 400 `application_required` without it. An upstream is neither unbound nor re-bound (`binding_refused`)."
},
"auth_format": {
"type": "string",
"maxLength": 200,
"minLength": 7,
"description": "How the header value is formed around the key, with `{value}` standing for the key — for example `Bearer {value}`. `{value}` alone where none is given."
},
"auth_header": {
"type": "string",
"pattern": "^[a-zA-Z0-9-]{1,64}$",
"description": "The HTTP header the key is sent in — for example `Authorization` or `x-api-key`."
},
"token_shape": {
"type": "string",
"pattern": "^(gemini|anthropic)$",
"description": "How token counts are read from this upstream's answers: `gemini` or `anthropic`. Omit for an upstream that reports none."
},
"sdk_settings": {
"anyOf": [
{
"type": "object",
"required": [
"base_url"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$",
"description": "The setting that receives the egress key, a credential the platform mints for this upstream and environment at each deploy, promote, and restart. It reaches this upstream's route alone, and the gateway swaps it for the stored key, so the stored key never enters the container. Absent, the container receives no key setting for this upstream. The name rules are `base_url`'s."
},
"base_url": {
"type": "string",
"pattern": "^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$",
"description": "Required where `sdk_settings` is given: the setting that receives the gateway's address for this upstream, the gateway origin the deploy injects, then `/egress/v0/<name>`, then `base_path`. An upper-case letter first, then upper-case letters, digits, or underscores, ending in a letter or a digit. A name the platform sets, or one a manifest binding or another upstream of the application already uses, is refused `invalid_request`."
},
"base_path": {
"type": "string",
"pattern": "^(\\/[A-Za-z0-9._~%-]+)+$",
"maxLength": 200,
"description": "The path `base_url`'s value ends with, such as `/v1` for a client that appends `/chat/completions` to its base URL. Absent, the value ends at the upstream's name."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Optional: the settings an unchanged client of this upstream reads in a deployed container, such as a provider's SDK. The manifest's `settings` is another member, which binds a stored value into the container; these name the settings the platform fills so the stored key stays at the gateway. Each deploy, promote, and `restart_application` of the bound application sets `base_url`'s setting to the gateway's address for this upstream, and `key`'s setting to an egress key the platform mints for this upstream and environment. The gateway swaps the egress key for the stored key at its edge, and the egress key works on this upstream alone. A revision that omits `sdk_settings` keeps the standing ones. `null` removes them, and `sdk_settings` without `key` drops the key setting; either ends the upstream's egress keys in both environments, which the answer's `egress_keys_ended` counts."
},
"credential_name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "The name the key was stored under with `store_secret`."
}
}
}