Environments
Environments
Environments endpoints of the Ellipsis REST API.
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/environments | write:environments |
Token access
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Sessions can reference its name or ID.
curl -X POST "https://api.ellipsis.dev/v1/environments" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.CreateEnvironmentRequest.model_validate(
{
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
}
)
result = client.environments.create(request.environment)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.environments.create>[0] = {
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
};
const result = await client.environments.create(request);
console.log(result);Request
Example request body
{
}
Body parameters
environmentEnvironmentDocument-Inputrequired
The environment's definition.
Response
Example response, 201
{
}
| Method | Path | Required permissions |
|---|---|---|
| GET | /v1/environments | read:environments |
Token access
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
curl "https://api.ellipsis.dev/v1/environments" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.environments.list()
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.environments.list();
console.log(result);Request
Response
Example response, 200
{
}
| Method | Path | Required permissions |
|---|---|---|
| GET | /v1/environments/{environment_id} | read:environments |
Token access
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Path parameters
environment_idstringrequired
curl "https://api.ellipsis.dev/v1/environments/{environment_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.environments.get("api-environment")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.environments.get("api-environment");
console.log(result);Request
Response
Example response, 200
{
}
| Method | Path | Required permissions |
|---|---|---|
| PUT | /v1/environments/{environment_id} | write:environments |
Token access
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Git-managed definitions must be edited in their repository.
Path parameters
environment_idstringrequired
curl -X PUT "https://api.ellipsis.dev/v1/environments/{environment_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.UpdateEnvironmentRequest.model_validate(
{
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
}
)
result = client.environments.update(
"api-environment",
request.environment,
)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.environments.update>[1] = {
"environment": {
"ellipsis": {
"kind": "environment",
"name": "api-environment",
"metadata": {
"labels": [],
"annotations": {}
}
},
"repositories": [
{
"name": "api-repo"
}
],
"compute": {},
"hooks": {},
"mcp_servers": [],
"variables": []
}
};
const result = await client.environments.update("api-environment", request);
console.log(result);Request
Example request body
{
}
Body parameters
environmentEnvironmentDocument-Inputrequired
The environment's new definition. Replaces the previous one wholesale , this is not a partial update.
Response
Example response, 200
{
}
| Method | Path | Required permissions |
|---|---|---|
| DELETE | /v1/environments/{environment_id} | delete:environments |
Token access
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
New sessions referencing it will fail.
Path parameters
environment_idstringrequired
curl -X DELETE "https://api.ellipsis.dev/v1/environments/{environment_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.environments.delete("api-environment")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.environments.delete("api-environment");
console.log(result);