Create Session

POST /v1/sessions/session

Creates a new session for a user given an API key.

Args: api_key: User's API key vm_lifetime_seconds: How long the VM will live (in seconds) from spawn time. Min: 20s, Max: 86400s (24h), Default: 300s (5min) memory_mb: VM memory in MB (128-8192). Default: uses system default. Memory is hotplugged after VM restore if virtio-mem is configured. vcpu_count: VM vCPU count (1, 2, 4, 6, 8). Default: 2. Determines which snapshot folder to use (snap1, snap2, snap4, snap6, snap8). metadata: Optional user-defined metadata for filtering (key-value pairs). env: Optional environment variables to set in the VM (key-value pairs). If provided, a VM will be spawned immediately and the env vars will be configured. Env vars persist across all executions in this session.

Request Body

Required: Yes

application/json

Resolved schema:

{
  "properties": {
    "api_key": {
      "type": "string",
      "title": "Api Key"
    },
    "vm_lifetime_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Vm Lifetime Seconds"
    },
    "memory_mb": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Memory Mb"
    },
    "vcpu_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Vcpu Count"
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata"
    },
    "env": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Env"
    }
  },
  "type": "object",
  "required": [
    "api_key"
  ],
  "title": "CreateSessionRequest"
}

Field details:

Field	Type	Required	Description	Constraints
api_key	string	Yes
vm_lifetime_seconds	integer | null	No		nullable
memory_mb	integer | null	No		nullable
vcpu_count	integer | null	No		nullable
metadata	object | null	No		nullable
env	object<string, string> | null	No		nullable
env.*	string	No

Responses

200

Successful Response

application/json

Resolved schema:

{
  "properties": {
    "session_id": {
      "type": "string",
      "format": "uuid",
      "title": "Session Id"
    }
  },
  "type": "object",
  "required": [
    "session_id"
  ],
  "title": "CreateSessionResponse"
}

Field details:

Field	Type	Required	Description	Constraints
session_id	string	Yes		format=uuid

422

Validation Error

application/json

Resolved schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Field details:

Field	Type	Required	Description	Constraints
detail	array<object>	No
detail[]	object	No
detail[].loc	array<string | integer>	No
detail[].loc[]	string | integer	No
detail[].msg	string	No
detail[].type	string	No