Koo Docs
View as Markdown

Variables

List a project’s variables, newest first

GET/accounts/{accountId}/projects/{projectId}/variables
Rolesreadereditoradminowner
Parameters
limitnumberquery

Page size (1–100, default 20).

cursorstringquery

Opaque cursor (page.nextCursor).

accountIdstringpathrequired
projectIdstringpathrequired
Returns
200 · VariablesPageDto
dataobject[]read-only
pageobjectread-only
cURL
GET /accounts/{accountId}/projects/{projectId}/variables
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
Request body
namestringrequired

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.

valuestring

A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.

connectionobject

Source the value from a managed addon’s published key (the `connection` kind).

aliasTargetstring

Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.

sensitiveboolean

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
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
POST /accounts/{accountId}/projects/{projectId}/variables
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"    }'
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
Request body
setobject[]

Variables to create or overwrite, by name.

unsetstring[]

Names of variables to remove.

confirmImpactboolean

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
dataobject[]read-only

The variables that now exist after the batch (the set/overwritten rows), metadata only.

appliedintegerread-only

How many variables were created or overwritten.

removedintegerread-only

How many variables were removed.

cURL
POST /accounts/{accountId}/projects/{projectId}/variables/batch
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
GET /accounts/{accountId}/projects/{projectId}/variables/{variableName}
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName \  -H "Authorization: Bearer kc_your_api_token"
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
Request body
valuestring

Replace the literal value (opaque variables).

connectionobject

Re-point at a managed addon’s published key.

aliasTargetstring

Re-point the alias at another variable.

sensitiveboolean

Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
PATCH /accounts/{accountId}/projects/{projectId}/variables/{variableName}
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
Request body
confirmImpactboolean

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
cURL
DELETE /accounts/{accountId}/projects/{projectId}/variables/{variableName}
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
Rolesreadereditoradminowner

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
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
Returns
200 · VariableImpactDto
servicesobject[]read-only

Services a write or delete of this variable at the queried scope actually reaches.

totalintegerread-only

How many services are affected.

cURL
GET /accounts/{accountId}/projects/{projectId}/variables/{variableName}/impact
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName/impact \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner

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

Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
Returns
200 · RevealedVariableDto
namestringread-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.

valuestringread-only

The variable’s plaintext value (returned by the audited reveal endpoint).

cURL
POST /accounts/{accountId}/projects/{projectId}/variables/{variableName}/reveal
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/variables/:variableName/reveal \  -X POST \  -H "Authorization: Bearer kc_your_api_token"
Response
json
{  "name": "my-app",  "value": "example"}

List an environment’s variables, newest first

GET/accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables
Rolesreadereditoradminowner
Parameters
limitnumberquery

Page size (1–100, default 20).

cursorstringquery

Opaque cursor (page.nextCursor).

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Returns
200 · VariablesPageDto
dataobject[]read-only
pageobjectread-only
cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Request body
namestringrequired

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.

valuestring

A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.

connectionobject

Source the value from a managed addon’s published key (the `connection` kind).

aliasTargetstring

Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.

sensitiveboolean

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
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables
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"    }'
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Request body
setobject[]

Variables to create or overwrite, by name.

unsetstring[]

Names of variables to remove.

confirmImpactboolean

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
dataobject[]read-only

The variables that now exist after the batch (the set/overwritten rows), metadata only.

appliedintegerread-only

How many variables were created or overwritten.

removedintegerread-only

How many variables were removed.

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/batch
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName \  -H "Authorization: Bearer kc_your_api_token"
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Request body
valuestring

Replace the literal value (opaque variables).

connectionobject

Re-point at a managed addon’s published key.

aliasTargetstring

Re-point the alias at another variable.

sensitiveboolean

Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
PATCH /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Request body
confirmImpactboolean

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
cURL
DELETE /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}
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
Rolesreadereditoradminowner

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
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Returns
200 · VariableImpactDto
servicesobject[]read-only

Services a write or delete of this variable at the queried scope actually reaches.

totalintegerread-only

How many services are affected.

cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}/impact
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName/impact \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner

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

Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
Returns
200 · RevealedVariableDto
namestringread-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.

valuestringread-only

The variable’s plaintext value (returned by the audited reveal endpoint).

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/variables/{variableName}/reveal
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/variables/:variableName/reveal \  -X POST \  -H "Authorization: Bearer kc_your_api_token"
Response
json
{  "name": "my-app",  "value": "example"}

List a service’s variables, newest first

GET/accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables
Rolesreadereditoradminowner
Parameters
limitnumberquery

Page size (1–100, default 20).

cursorstringquery

Opaque cursor (page.nextCursor).

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Returns
200 · VariablesPageDto
dataobject[]read-only
pageobjectread-only
cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Request body
namestringrequired

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.

valuestring

A literal value (the `opaque` kind). Provide exactly one of value, connection, or aliasTarget.

connectionobject

Source the value from a managed addon’s published key (the `connection` kind).

aliasTargetstring

Point at another variable resolved through the scope chain (the `alias` kind); it inherits the target’s sensitivity.

sensitiveboolean

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
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables
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"    }'
Response
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
Rolesreadereditoradminowner

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
accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Returns
200 · ResolvedVariablesDto
dataobject[]read-only

The effective variables the service receives (project ∪ environment ∪ service, nearest wins).

danglingobject[]read-only

Connections and aliases that failed to resolve, each with a typed reason.

cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/resolved-variables
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/resolved-variables \  -H "Authorization: Bearer kc_your_api_token"
Response
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
Rolesreadereditoradminowner
Parameters
accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Request body
setobject[]

Variables to create or overwrite, by name.

unsetstring[]

Names of variables to remove.

confirmImpactboolean

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
dataobject[]read-only

The variables that now exist after the batch (the set/overwritten rows), metadata only.

appliedintegerread-only

How many variables were created or overwritten.

removedintegerread-only

How many variables were removed.

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/batch
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
GET /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}
bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/services/:name/variables/:variableName \  -H "Authorization: Bearer kc_your_api_token"
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Request body
valuestring

Replace the literal value (opaque variables).

connectionobject

Re-point at a managed addon’s published key.

aliasTargetstring

Re-point the alias at another variable.

sensitiveboolean

Flip whether the value is withheld from ordinary reads. Only valid for a literal-value (opaque) variable.

Returns
200 · VariableDto
idstringread-only

Unique identifier of the variable (read-only).

namestringrequired

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).

scopeIdstringread-only

Id of the resource the variable is scoped to (project, environment, or service).

sensitivebooleanrequired

When true, the value is withheld from ordinary reads and returned only by the audited reveal endpoint.

valuestring

The value — present only for a non-sensitive variable; a sensitive value is withheld and must be revealed one at a time.

connectionobject

Present for a connection variable — the managed addon and key it injects.

aliasTargetstring

Present for an alias variable — the name of the variable it resolves to through the scope chain.

createdAtstring <date-time>read-only

When the variable was created.

updatedAtstring <date-time>read-only

When the variable was last changed.

cURL
PATCH /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}
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 '{}'
Response
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}
Rolesreadereditoradminowner
Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Request body
confirmImpactboolean

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
cURL
DELETE /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}
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
Rolesreadereditoradminowner

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

Parameters
variableNamestringpathrequired

The variable’s name — its identity within the scope.

accountIdstringpathrequired
projectIdstringpathrequired
environmentIdstringpathrequired
namestringpathrequired

Service name within the environment.

Returns
200 · RevealedVariableDto
namestringread-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.

valuestringread-only

The variable’s plaintext value (returned by the audited reveal endpoint).

cURL
POST /accounts/{accountId}/projects/{projectId}/environments/{environmentId}/services/{name}/variables/{variableName}/reveal
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"
Response
json
{  "name": "my-app",  "value": "example"}