Upsert an env entry

PUT

/v1/env/{name}

const url = 'https://example.com/v1/env/example?envName=example&scopeKind=tenant';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"scope":{"kind":"tenant","tenantId":"example"},"envName":"example","name":"example","value":"example","tags":{"additionalProperty":"example"},"ifRevision":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url 'https://example.com/v1/env/example?envName=example&scopeKind=tenant' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "scope": { "kind": "tenant", "tenantId": "example" }, "envName": "example", "name": "example", "value": "example", "tags": { "additionalProperty": "example" }, "ifRevision": 1 }'

Requires the env:write capability. Every write bumps revision; optional ifRevision guards against concurrent updates (409 env-write-conflict). Env values aren’t secret: they’re recorded with each run that uses them. A credential goes in /v1/secrets.

Authorizations

bearerAuth

Parameters

Path Parameters

name

required

string

>= 1 characters

Env entry name (opaque string within the tenant + envName).

Query Parameters

envName

required

Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.

string

/^[a-z][a-z0-9-]{0,62}$/

[a-z][a-z0-9-]{0,62}. Required on every env + secrets route.

scopeKind

required

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Required on every env + secrets route. Tenant carries no scopeId; org / project require scopeId.

scopeId

string

>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

object

scope

One of:

object

kind

required

string

Allowed values: tenant

tenantId

required

string

envName

Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.

string

/^[a-z][a-z0-9-]{0,62}$/

name

string

>= 1 characters

value

required

string

tags

object

key

additional properties

string

ifRevision

integer

Responses

200

Env record.

application/json

object

scope

required

One of:

object

kind

required

string

Allowed values: tenant

tenantId

required

string

envName

required

Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.

string

/^[a-z][a-z0-9-]{0,62}$/

name

required

string

value

required

string

revision

required

integer

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

tags

object

key

additional properties

string

Example

{
  "scope": {
    "kind": "tenant"
  }
}

400

Malformed request body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Bearer token missing env:write capability.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

ifRevision mismatch (env-write-conflict). Or env-not-served: this runtime keeps every value under the env it serves (whoami’s servedEnv, with refusesOtherEnvs), so a value under another env would never be read. details.envName is the env asked for, details.servedEnv the one to use. A secret that a provider, MCP endpoint or webhook endpoint registered before names under that env, at the scope it’s read at, is still written: it’s read there. Nothing is stored otherwise.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Upsert an env entry

Authorizations

Parameters

Path Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated