ReferenceAPI

Create a computer

Create a computer in the workspace given, with a generated name like bright-anchovy when omitted.

POST https://api.nevia.cloud/v1/computers
curl -X POST "https://api.nevia.cloud/v1/computers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 8f1c2a7e-3b4d-4c5e-9f0a-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
    "name": "api-staging",
    "image": "docker.io/library/python:3.13-slim",
    "ports": [
      {
        "published": 8080,
        "target": 8080
      }
    ]
  }'
{
  "computer": {
    "id": "01d4cnjk3xg90y576w8y6t4gdwm",
    "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
    "name": "api-staging",
    "state": "ready",
    "pending": null,
    "image": "docker.io/library/python:3.13-slim",
    "image_digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "ports": [
      {
        "published": 8080,
        "target": 8080,
        "protocol": "http1",
        "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example:8080"
      }
    ],
    "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example",
    "env_keys": [
      "LOG_LEVEL",
      "OPENAI_KEY"
    ],
    "env_vars": [
      {
        "name": "LOG_LEVEL",
        "source": "literal",
        "missing": false
      },
      {
        "name": "OPENAI_KEY",
        "source": "secret",
        "missing": false
      }
    ],
    "generation": 1,
    "protected": false,
    "parent": null,
    "from_checkpoint": null,
    "error": null,
    "created_at": "2026-09-10T12:34:56Z",
    "last_started_at": "2026-09-10T12:35:12Z",
    "last_active_at": "2026-09-10T12:40:03Z",
    "deleted_at": null
  },
  "operations": [
    "01d4cnjm89yk0r3xtv80dy0x7by"
  ]
}

Authorization

bearerAuth
Authorization Bearer <token>

Send the token in the Authorization: Bearer <token> header. See Authenticate.

In: header

Header Parameters

Idempotency-Key* string

Retry key. A retry with the same key and body replays the first response

Length 1 <= length <= 255

Request Body

application/json

Settings for a new computer

Behavior

With from_checkpoint, the machine restores the checkpoint's snapshot with its image, env and ports. The platform gives each port mapping an HTTPS listener on its assigned hostname. It sets url and ports[].url once the computer is ready.

The API stores env and does not send it to the machine. Each exec applies it. The computer's startup process does not see it. Values may be templates: {{secrets.NAME}} and {{variables.NAME}} name entries in the workspace. Templates resolve by name at each exec, so a secret's value never reaches the control plane. Branches and restores keep the stored env. PATCH changes it.

The computer.create operation finishes in the 200 response. If the machine does not come up in the short wait, the response is 202, and the operation keeps running.

Response

application/json

The computer, ready or failed, when it came up within the short wait.