Environments
Create the environments an organization runs apps in, set their caps and budget, and read the defaults they inherit.
Introduction
An environment is the place an app id runs in, and every other app route takes its name in environment. Omitted, they address production, which every organization has.
The two halves of this page are separate: an environment carries the caps and the budget set on it, and the organization carries the defaults an environment inherits for every field it leaves empty. Each environment reports both, the second under resolved.
production is created on the first read that needs it, so an organization that has never opened this page still lists one.
List environments
Returns the organization's environments, production first and then by name. production is the environment an operation targets when none is named, and it is created here when the organization does not have it yet, except for an organization whose deletion is pending. q narrows the list to names containing it, ignoring case. Each entry carries the values set on the environment and, under resolved, the values in force after inheriting the organization defaults.
Request
q
stringmin: 1max: 63Case-insensitive substring of the environment name. Omit to list every environment.
Response
data
object[]requiredArray items11 properties each
name
stringrequiredmin: 1max: 63Lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit, at most 63 characters. Unique among the organization's live environments and immutable.
productionis every organization's default.
isDefault
booleanrequiredTrue for
production, the environment an operation targets when none is named. It cannot be deleted.
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. Spend is read from settlement, which trails usage by a few minutes and a worker's end-of-life adjustment by up to about twenty, and leaves out usage a capacity commitment covers. Empty means no cap.
budgetAlertPercents
integer[]requiredPercentages of the budget at which the organization's users are emailed, ascending. Each is sent at most once per UTC month, even when the budget changes later in the month; percents reached together send one alert, for the highest. A
"0.00"budget alerts on the first spend above zero. Empty sends no alert.
pauseAtBudget
booleanrequiredWhether the environment is paused once its spend this UTC month reaches the budget: its apps are stopped, and invocation and requests that add capacity are refused until the budget is raised past the spend or the month turns. A budget of zero pauses at the first spend.
unauthenticatedAccess
stringnullableAs set on the environment. Empty inherits the organization default;
resolvedcarries the setting in force.Possible values1 value
resolved
objectrequiredThe values in force after inheritance: the environment's own value where it set one, the organization default otherwise.
Properties3 properties
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment may expose its endpoints without an API key.
Possible values2 values
createdAt
string (date-time)requireddate-time
updatedAt
string (date-time)requireddate-time
Errors
| Status | When |
401 | Missing or invalid credentials |
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 |
Create an environment
Creates an environment under a name no live environment holds; a deleted environment's name can be reused. A limit left empty inherits the organization default, a budget left empty means no cap, and unauthenticatedAccess left empty inherits the organization default. Returns 409 when a live environment already has the name. An organization whose deletion is pending returns 403.
Request
name
stringrequiredmin: 1max: 63Lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit, at most 63 characters. Unique among the organization's live environments and immutable.
productionis every organization's default.
maxConcurrentWorkers
integernullableint32min: 0Cap on the workers the environment holds, checked when a request adds capacity. Omit, or send
null, to inherit the organization default.
maxConcurrentGpus
integernullableint32min: 0Cap on the GPUs the environment holds, checked when a request adds capacity. Omit, or send
null, to inherit the organization default.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. USD, written with one to six decimal places (
"500.00");"0.00"is a cap reached at once. Omit, or sendnull, for no cap.
budgetAlertPercents
integer[]max items: 10Percentages of the budget at which the organization's users are emailed, each once per month. Stored ascending with duplicates removed; an empty array sends no alert. Omit for 50, 80 and 100.
pauseAtBudget
booleanPause the environment once its spend this UTC month reaches the budget: stop its apps, and refuse invocation and requests that add capacity until the budget is raised past the spend or the month turns. Omit for
false.
unauthenticatedAccess
stringnullableOmit, or send
null, to inherit the organization default.Allowed values1 value
Response
name
stringrequiredmin: 1max: 63Lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit, at most 63 characters. Unique among the organization's live environments and immutable.
productionis every organization's default.
isDefault
booleanrequiredTrue for
production, the environment an operation targets when none is named. It cannot be deleted.
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. Spend is read from settlement, which trails usage by a few minutes and a worker's end-of-life adjustment by up to about twenty, and leaves out usage a capacity commitment covers. Empty means no cap.
budgetAlertPercents
integer[]requiredPercentages of the budget at which the organization's users are emailed, ascending. Each is sent at most once per UTC month, even when the budget changes later in the month; percents reached together send one alert, for the highest. A
"0.00"budget alerts on the first spend above zero. Empty sends no alert.
pauseAtBudget
booleanrequiredWhether the environment is paused once its spend this UTC month reaches the budget: its apps are stopped, and invocation and requests that add capacity are refused until the budget is raised past the spend or the month turns. A budget of zero pauses at the first spend.
unauthenticatedAccess
stringnullableAs set on the environment. Empty inherits the organization default;
resolvedcarries the setting in force.Possible values1 value
resolved
objectrequiredThe values in force after inheritance: the environment's own value where it set one, the organization default otherwise.
Properties3 properties
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment may expose its endpoints without an API key.
Possible values2 values
createdAt
string (date-time)requireddate-time
updatedAt
string (date-time)requireddate-time
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 |
403 | Authenticated but not permitted to access this resource |
409 | Resource already exists or the request conflicts with its current state |
413 | The request body exceeds its size limit: 10 MiB on invoke-sync and invoke-async, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. detail names the limit in bytes.
|
415 | The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of application/json that cannot be parsed returns 400. One that parses and breaks the schema returns 422. A body sent with no Content-Type is the same refusal.
|
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 environment
Returns one environment, with the values set on it and the values in force after inheritance. production is created here when the organization does not have it yet.
Request
environmentName
stringrequiredmin: 1max: 63Name of one of the authenticated organization's live environments.
Response
name
stringrequiredmin: 1max: 63Lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit, at most 63 characters. Unique among the organization's live environments and immutable.
productionis every organization's default.
isDefault
booleanrequiredTrue for
production, the environment an operation targets when none is named. It cannot be deleted.
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. Spend is read from settlement, which trails usage by a few minutes and a worker's end-of-life adjustment by up to about twenty, and leaves out usage a capacity commitment covers. Empty means no cap.
budgetAlertPercents
integer[]requiredPercentages of the budget at which the organization's users are emailed, ascending. Each is sent at most once per UTC month, even when the budget changes later in the month; percents reached together send one alert, for the highest. A
"0.00"budget alerts on the first spend above zero. Empty sends no alert.
pauseAtBudget
booleanrequiredWhether the environment is paused once its spend this UTC month reaches the budget: its apps are stopped, and invocation and requests that add capacity are refused until the budget is raised past the spend or the month turns. A budget of zero pauses at the first spend.
unauthenticatedAccess
stringnullableAs set on the environment. Empty inherits the organization default;
resolvedcarries the setting in force.Possible values1 value
resolved
objectrequiredThe values in force after inheritance: the environment's own value where it set one, the organization default otherwise.
Properties3 properties
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment may expose its endpoints without an API key.
Possible values2 values
createdAt
string (date-time)requireddate-time
updatedAt
string (date-time)requireddate-time
Errors
| Status | When |
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 |
Update an environment
Changes the fields the body names and leaves the rest as they are. A field sent as null is cleared: a limit inherits the organization default again, the budget is removed, and unauthenticatedAccess inherits the organization default again. The name cannot change. production takes every change an environment takes. An organization whose deletion is pending returns 403.
Request
environmentName
stringrequiredmin: 1max: 63Name of one of the authenticated organization's live environments.
maxConcurrentWorkers
integernullableint32min: 0Cap on the workers the environment holds, checked when a request adds capacity.
nullinherits the organization default again.
maxConcurrentGpus
integernullableint32min: 0Cap on the GPUs the environment holds, checked when a request adds capacity.
nullinherits the organization default again.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. USD, written with one to six decimal places (
"500.00");"0.00"is a cap reached at once.nullremoves the cap.
budgetAlertPercents
integer[]max items: 10Percentages of the budget at which the organization's users are emailed, each once per month. Stored ascending with duplicates removed; an empty array sends no alert.
pauseAtBudget
booleanPause the environment once its spend this UTC month reaches the budget: stop its apps, and refuse invocation and requests that add capacity until the budget is raised past the spend or the month turns.
unauthenticatedAccess
stringnullablenullinherits the organization default again.Allowed values1 value
Response
name
stringrequiredmin: 1max: 63Lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit, at most 63 characters. Unique among the organization's live environments and immutable.
productionis every organization's default.
isDefault
booleanrequiredTrue for
production, the environment an operation targets when none is named. It cannot be deleted.
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity, as set on the environment. Empty inherits the organization default;
resolvedcarries the cap in force.
monthlyBudget
objectnullablePay-as-you-go spend cap for the calendar month, which resets on the 1st at 00:00 UTC. Spend is read from settlement, which trails usage by a few minutes and a worker's end-of-life adjustment by up to about twenty, and leaves out usage a capacity commitment covers. Empty means no cap.
budgetAlertPercents
integer[]requiredPercentages of the budget at which the organization's users are emailed, ascending. Each is sent at most once per UTC month, even when the budget changes later in the month; percents reached together send one alert, for the highest. A
"0.00"budget alerts on the first spend above zero. Empty sends no alert.
pauseAtBudget
booleanrequiredWhether the environment is paused once its spend this UTC month reaches the budget: its apps are stopped, and invocation and requests that add capacity are refused until the budget is raised past the spend or the month turns. A budget of zero pauses at the first spend.
unauthenticatedAccess
stringnullableAs set on the environment. Empty inherits the organization default;
resolvedcarries the setting in force.Possible values1 value
resolved
objectrequiredThe values in force after inheritance: the environment's own value where it set one, the organization default otherwise.
Properties3 properties
maxConcurrentWorkers
integernullableint32Cap on the workers the environment holds, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32Cap on the GPUs the environment holds, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment may expose its endpoints without an API key.
Possible values2 values
createdAt
string (date-time)requireddate-time
updatedAt
string (date-time)requireddate-time
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 |
403 | Authenticated but not permitted to access this resource |
404 | Resource not found |
413 | The request body exceeds its size limit: 10 MiB on invoke-sync and invoke-async, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. detail names the limit in bytes.
|
415 | The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of application/json that cannot be parsed returns 400. One that parses and breaks the schema returns 422. A body sent with no Content-Type is the same refusal.
|
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 |
Delete an environment
Deletes an environment that has no live app and no secret. An environment that still has either answers 409, and so does production, which every organization keeps. The name becomes available to a new environment; a deleted app's history still names the environment it ran in. An organization whose deletion is pending returns 403.
Request
environmentName
stringrequiredmin: 1max: 63Name of one of the authenticated organization's live environments.
Errors
| Status | When |
401 | Missing or invalid credentials |
403 | Authenticated but not permitted to access this resource |
404 | Resource not found |
409 | Resource already exists or the request conflicts with its current state |
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 the organization defaults
Returns the limits and the access setting an environment inherits for every field it leaves empty. An organization that has never set them has no caps and allows unauthenticated access. The worker and GPU caps are checked on create, on a source change to an initializing, active or failed app, on a configuration change that adds workers or GPUs or restarts a failed app, on a deploy that rolls out, and on resume, against each app's larger of its live workers and its keep-warm floor; they do not bound autoscaling. Unauthenticated access is stored but not yet enforced.
Response
maxConcurrentWorkers
integernullableint32min: 0Worker cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32min: 0GPU cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment in an environment that sets nothing of its own may expose its endpoints without an API key.
Possible values2 values
Errors
| Status | When |
401 | Missing or invalid credentials |
500 | Unexpected server error |
503 | A required service is temporarily unavailable |
Replace the organization defaults
Replaces the organization defaults as a whole: a limit left out of the body means no cap. The change reaches every environment that inherits the field at once; it does not roll apps already running. An organization whose deletion is pending returns 403.
Request
maxConcurrentWorkers
integernullableint32min: 0Worker cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32min: 0GPU cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment in an environment that sets nothing of its own may expose its endpoints without an API key.
Allowed values2 values
Response
maxConcurrentWorkers
integernullableint32min: 0Worker cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
maxConcurrentGpus
integernullableint32min: 0GPU cap of an environment that sets none of its own, checked when a request adds capacity. Empty means no cap.
unauthenticatedAccess
stringrequiredWhether a new deployment in an environment that sets nothing of its own may expose its endpoints without an API key.
Possible values2 values
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 |
403 | Authenticated but not permitted to access this resource |
413 | The request body exceeds its size limit: 10 MiB on invoke-sync and invoke-async, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. detail names the limit in bytes.
|
415 | The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of application/json that cannot be parsed returns 400. One that parses and breaks the schema returns 422. A body sent with no Content-Type is the same refusal.
|
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 |