# Variables

### List a project’s variables, newest first

`GET /accounts/{accountId}/projects/{projectId}/variables`

**Required role:** reader

**Parameters**

- `limit` _(query)_ · `number` · optional — Page size (1–100, default 20).
- `cursor` _(query)_ · `string` · optional — Opaque cursor (page.nextCursor).
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Returns**

- `200` · `VariablesPageDto`

Attributes of `VariablesPageDto`:

- `data` · `object[]` · read-only
- `page` · `object` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "page": {
    "nextCursor": "example",
    "hasMore": true
  }
}
```

### Create a project-scoped variable

`POST /accounts/{accountId}/projects/{projectId}/variables`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Request body**

- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · optional — A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.
- `connection` · `object` · optional — Source the value from a managed addon’s published key (the `connection` kind).
- `aliasTarget` · `string` · optional — Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.
- `sensitive` · `boolean` · optional — Withhold the value from ordinary reads (reveal it via the audited endpoint). Only valid with a literal `value` — connection sensitivity is derived and alias sensitivity is inherited.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-app"
    }'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Apply a merge-shaped batch of project variables (atomic)

`POST /accounts/{accountId}/projects/{projectId}/variables/batch`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Request body**

- `set` · `object[]` · optional — Variables to create or overwrite, by name.
- `unset` · `string[]` · optional — Names of variables to remove.
- `confirmImpact` · `boolean` · optional — Acknowledge that unsetting a project- or environment-scoped variable in this batch affects one or more services (§4.4). Required for that unset; never needed at service scope, and irrelevant to `set`.

**Returns**

- `200` · `BatchVariablesResultDto`

Attributes of `BatchVariablesResultDto`:

- `data` · `object[]` · read-only — The variables that now exist after the batch (the set/overwritten rows), metadata only.
- `applied` · `integer` · read-only — How many variables were created or overwritten.
- `removed` · `integer` · read-only — How many variables were removed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/batch \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "applied": 0,
  "removed": 0
}
```

### Get a project-scoped variable

`GET /accounts/{accountId}/projects/{projectId}/variables/{variableName}`

**Required role:** reader

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Update a project-scoped variable

`PATCH /accounts/{accountId}/projects/{projectId}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Request body**

- `value` · `string` · optional — Replace the literal value (opaque variables).
- `connection` · `object` · optional — Re-point at a managed addon’s published key.
- `aliasTarget` · `string` · optional — Re-point the alias at another variable.
- `sensitive` · `boolean` · optional — Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName \
  -X PATCH \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Delete a project-scoped variable

`DELETE /accounts/{accountId}/projects/{projectId}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Request body**

- `confirmImpact` · `boolean` · optional — Acknowledge that deleting this project- or environment-scoped variable affects one or more services (they lose the value or fall back to a wider scope). Required for that delete; never needed for a service-scoped one.

**Returns**

- `204`

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName \
  -X DELETE \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### The services a project-scoped write/delete of this variable reaches (blast radius)

`GET /accounts/{accountId}/projects/{projectId}/variables/{variableName}/impact`

**Required role:** reader

The services that resolve this variable at project scope (excluding services that shadow the name and managed addons). Same scope query the delete confirmImpact guard uses (§8.1).

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Returns**

- `200` · `VariableImpactDto`

Attributes of `VariableImpactDto`:

- `services` · `object[]` · read-only — Services a write or delete of this variable at the queried scope actually reaches.
- `total` · `integer` · read-only — How many services are affected.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName/impact \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "services": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "environmentId": "environment_01example0000000000000000x"
    }
  ],
  "total": 0
}
```

### Reveal a project-scoped variable’s value (audited)

`POST /accounts/{accountId}/projects/{projectId}/variables/{variableName}/reveal`

**Required role:** reader

Returns the plaintext once and writes a `variable.reveal` audit event. Any viewer.

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required

**Returns**

- `200` · `RevealedVariableDto`

Attributes of `RevealedVariableDto`:

- `name` · `string` · read-only — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · read-only — The variable’s plaintext value (returned by the audited reveal endpoint).

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName/reveal \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "name": "my-app",
  "value": "example"
}
```

### List an environment’s variables, newest first

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables`

**Required role:** reader

**Parameters**

- `limit` _(query)_ · `number` · optional — Page size (1–100, default 20).
- `cursor` _(query)_ · `string` · optional — Opaque cursor (page.nextCursor).
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Returns**

- `200` · `VariablesPageDto`

Attributes of `VariablesPageDto`:

- `data` · `object[]` · read-only
- `page` · `object` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "page": {
    "nextCursor": "example",
    "hasMore": true
  }
}
```

### Create an environment-scoped variable

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Request body**

- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · optional — A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.
- `connection` · `object` · optional — Source the value from a managed addon’s published key (the `connection` kind).
- `aliasTarget` · `string` · optional — Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.
- `sensitive` · `boolean` · optional — Withhold the value from ordinary reads (reveal it via the audited endpoint). Only valid with a literal `value` — connection sensitivity is derived and alias sensitivity is inherited.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-app"
    }'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Apply a merge-shaped batch of environment variables (atomic)

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/batch`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Request body**

- `set` · `object[]` · optional — Variables to create or overwrite, by name.
- `unset` · `string[]` · optional — Names of variables to remove.
- `confirmImpact` · `boolean` · optional — Acknowledge that unsetting a project- or environment-scoped variable in this batch affects one or more services (§4.4). Required for that unset; never needed at service scope, and irrelevant to `set`.

**Returns**

- `200` · `BatchVariablesResultDto`

Attributes of `BatchVariablesResultDto`:

- `data` · `object[]` · read-only — The variables that now exist after the batch (the set/overwritten rows), metadata only.
- `applied` · `integer` · read-only — How many variables were created or overwritten.
- `removed` · `integer` · read-only — How many variables were removed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/batch \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "applied": 0,
  "removed": 0
}
```

### Get an environment-scoped variable

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}`

**Required role:** reader

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Update an environment-scoped variable

`PATCH /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Request body**

- `value` · `string` · optional — Replace the literal value (opaque variables).
- `connection` · `object` · optional — Re-point at a managed addon’s published key.
- `aliasTarget` · `string` · optional — Re-point the alias at another variable.
- `sensitive` · `boolean` · optional — Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName \
  -X PATCH \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Delete an environment-scoped variable

`DELETE /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Request body**

- `confirmImpact` · `boolean` · optional — Acknowledge that deleting this project- or environment-scoped variable affects one or more services (they lose the value or fall back to a wider scope). Required for that delete; never needed for a service-scoped one.

**Returns**

- `204`

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName \
  -X DELETE \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### The services an environment-scoped write/delete of this variable reaches (blast radius)

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}/impact`

**Required role:** reader

The services that resolve this variable at environment scope (excluding services that shadow the name and managed addons). Same scope query the delete confirmImpact guard uses (§8.1).

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Returns**

- `200` · `VariableImpactDto`

Attributes of `VariableImpactDto`:

- `services` · `object[]` · read-only — Services a write or delete of this variable at the queried scope actually reaches.
- `total` · `integer` · read-only — How many services are affected.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName/impact \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "services": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "environmentId": "environment_01example0000000000000000x"
    }
  ],
  "total": 0
}
```

### Reveal an environment-scoped variable’s value (audited)

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}/reveal`

**Required role:** reader

Returns the plaintext once and writes a `variable.reveal` audit event. Any viewer.

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required

**Returns**

- `200` · `RevealedVariableDto`

Attributes of `RevealedVariableDto`:

- `name` · `string` · read-only — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · read-only — The variable’s plaintext value (returned by the audited reveal endpoint).

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName/reveal \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "name": "my-app",
  "value": "example"
}
```

### List a service’s variables, newest first

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables`

**Required role:** reader

**Parameters**

- `limit` _(query)_ · `number` · optional — Page size (1–100, default 20).
- `cursor` _(query)_ · `string` · optional — Opaque cursor (page.nextCursor).
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Returns**

- `200` · `VariablesPageDto`

Attributes of `VariablesPageDto`:

- `data` · `object[]` · read-only
- `page` · `object` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "page": {
    "nextCursor": "example",
    "hasMore": true
  }
}
```

### Create a service-scoped variable

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Request body**

- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · optional — A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.
- `connection` · `object` · optional — Source the value from a managed addon’s published key (the `connection` kind).
- `aliasTarget` · `string` · optional — Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.
- `sensitive` · `boolean` · optional — Withhold the value from ordinary reads (reveal it via the audited endpoint). Only valid with a literal `value` — connection sensitivity is derived and alias sensitivity is inherited.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-app"
    }'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### The effective variable environment a service receives (project ∪ environment ∪ service, nearest wins)

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/resolved-variables`

**Required role:** reader

Connections and aliases are materialised server-side; each entry carries its source scope and what it shadows, plus a dangling array. Sensitive values are withheld. 404 for a managed addon.

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Returns**

- `200` · `ResolvedVariablesDto`

Attributes of `ResolvedVariablesDto`:

- `data` · `object[]` · read-only — The effective variables the service receives (project ∪ environment ∪ service, nearest wins).
- `dangling` · `object[]` · read-only — Connections and aliases that failed to resolve, each with a typed reason.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/resolved-variables \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "name": "my-app",
      "sensitive": true,
      "value": "example",
      "source": "project",
      "sourceId": "source_01example0000000000000000x",
      "sourceScopeId": "sourcescope_01example0000000000000000x",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "shadows": [
        {
          "scope": "project",
          "scopeId": "scope_01example0000000000000000x",
          "id": "acct_01example0000000000000000x"
        }
      ]
    }
  ],
  "dangling": [
    {
      "name": "my-app",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "reason": "service_not_found"
    }
  ]
}
```

### Apply a merge-shaped batch of service variables (atomic)

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/batch`

**Required role:** editor

**Parameters**

- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Request body**

- `set` · `object[]` · optional — Variables to create or overwrite, by name.
- `unset` · `string[]` · optional — Names of variables to remove.
- `confirmImpact` · `boolean` · optional — Acknowledge that unsetting a project- or environment-scoped variable in this batch affects one or more services (§4.4). Required for that unset; never needed at service scope, and irrelevant to `set`.

**Returns**

- `200` · `BatchVariablesResultDto`

Attributes of `BatchVariablesResultDto`:

- `data` · `object[]` · read-only — The variables that now exist after the batch (the set/overwritten rows), metadata only.
- `applied` · `integer` · read-only — How many variables were created or overwritten.
- `removed` · `integer` · read-only — How many variables were removed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/batch \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "name": "my-app",
      "scope": "project",
      "scopeId": "scope_01example0000000000000000x",
      "sensitive": true,
      "value": "example",
      "connection": {
        "service": "example",
        "key": "example"
      },
      "aliasTarget": "example",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "applied": 0,
  "removed": 0
}
```

### Get a service-scoped variable

`GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}`

**Required role:** reader

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/:variableName \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Update a service-scoped variable

`PATCH /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Request body**

- `value` · `string` · optional — Replace the literal value (opaque variables).
- `connection` · `object` · optional — Re-point at a managed addon’s published key.
- `aliasTarget` · `string` · optional — Re-point the alias at another variable.
- `sensitive` · `boolean` · optional — Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

**Returns**

- `200` · `VariableDto`

Attributes of `VariableDto`:

- `id` · `string` · read-only — Unique identifier of the variable (read-only).
- `name` · `string` · required — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `scope` · `"project" | "environment" | "service"` · read-only — Where the variable lives: a project, one environment, or a single service (service overrides environment overrides project).
- `scopeId` · `string` · read-only — Id of the resource the variable is scoped to (project, environment, or service).
- `sensitive` · `boolean` · required — When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.
- `value` · `string` · optional — The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.
- `connection` · `object` · optional — Present for a connection variable — the managed addon and key it injects.
- `aliasTarget` · `string` · optional — Present for an alias variable — the name of the variable it resolves to through the scope chain.
- `createdAt` · `string <date-time>` · read-only — When the variable was created.
- `updatedAt` · `string <date-time>` · read-only — When the variable was last changed.

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/:variableName \
  -X PATCH \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "name": "my-app",
  "scope": "project",
  "scopeId": "scope_01example0000000000000000x",
  "sensitive": true,
  "value": "example",
  "connection": {
    "service": "example",
    "key": "example"
  },
  "aliasTarget": "example",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Delete a service-scoped variable

`DELETE /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}`

**Required role:** editor

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Request body**

- `confirmImpact` · `boolean` · optional — Acknowledge that deleting this project- or environment-scoped variable affects one or more services (they lose the value or fall back to a wider scope). Required for that delete; never needed for a service-scoped one.

**Returns**

- `204`

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/:variableName \
  -X DELETE \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Reveal a service-scoped variable’s value (audited)

`POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}/reveal`

**Required role:** reader

Returns the plaintext once and writes a `variable.reveal` audit event. Any viewer.

**Parameters**

- `variableName` _(path)_ · `string` · required — The variable’s name — its identity within the scope.
- `accountId` _(path)_ · `string` · required
- `projectId` _(path)_ · `string` · required
- `environmentId` _(path)_ · `string` · required
- `name` _(path)_ · `string` · required — Service name within the environment.

**Returns**

- `200` · `RevealedVariableDto`

Attributes of `RevealedVariableDto`:

- `name` · `string` · read-only — Variable name — the injected environment-variable name: letters, digits and underscores, starting with a letter or underscore (1–128 chars). Unique within its scope. `KOO_VARIABLES_REVISION` is reserved.
- `value` · `string` · read-only — The variable’s plaintext value (returned by the audited reveal endpoint).

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/:variableName/reveal \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "name": "my-app",
  "value": "example"
}
```