Start a session

TypeScript SDKThe npm client, generated from the API spec.Python SDKThe PyPI client, sync and async.

Method	Path	Required permissions
POST	/v1/sessions	write:sessions

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.

Grant match patterns can further restrict access to individual resources.

Select a harness explicitly. Omit environment to use the basic sandbox, or name a saved environment. Set interactive to false for one-shot work.

curl -X POST "https://api.ellipsis.dev/v1/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "harness": {
    "type": "claude_code"
  },
  "environment": "api-environment",
  "prompt": "Run the tests and report failures.",
  "interactive": false,
  "budget": 3
}'

import os

from ellipsis import Ellipsis
from ellipsis import models

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

request = models.StartSessionRequest.model_validate(
    {
      "harness": {
        "type": "claude_code"
      },
      "environment": "api-environment",
      "prompt": "Run the tests and report failures.",
      "interactive": False,
      "budget": 3
    }
)

result = client.sessions.start(
    request.harness,
    budget=request.budget,
    environment=request.environment,
    interactive=request.interactive,
    prompt=request.prompt,
)
print(result)

import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const request: Parameters<typeof client.sessions.start>[0] = {
  "harness": {
    "type": "claude_code"
  },
  "environment": "api-environment",
  "prompt": "Run the tests and report failures.",
  "interactive": false,
  "budget": 3
};

const result = await client.sessions.start(request);
console.log(result);

Request

Example request body

{

"environment": "api-environment",

"prompt": "Run the tests and report failures.",

"interactive": false,

"budget": 3

}

Body parameters

budgetnumber

The most this session may spend, in US dollars. Omitted, the organization's default applies. Above the organization's per-session ceiling is a 400.

environmentstring | EnvironmentConfig-Input

Where the session runs. A STRING is a saved environment's name or `env_...` id, substituted wholesale. An OBJECT is the whole environment for this session , `{}` is the bare sandbox. Omitted, the session runs in the built-in basic sandbox , nothing outside the request picks the environment.

force_rebuilddefault falseboolean

Skip the image cache for this session's initial provision: a fresh full build whose snapshot then refreshes the cache for later runs.

harnessHarnessOptions-Inputrequired

The explicitly selected harness and its native options.

imagesarray<ImageAttachment>

Images attached to the first message, base64 inline. Requires the model's images capability, which is not currently certified. Each becomes an `[Image #N]` placeholder in the prompt and an image block on turn 0. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.

instructionsInstructions-Input

Instructions appended to the harness's own prompt. Text and repository file references are resolved in order.

interactivedefault trueboolean

Whether the session stays open for messages after its first turn. Defaults to true and requires the model's interactive capability. Set false for a one-shot run, which must carry a prompt. See GET /v1/account/models for supported combinations.

metadatadefault {}object

Arbitrary string key/value metadata stored on the session.

outputOutputConfig

The structured-output exit contract for this session.

permissionsPermissionsConfig-Input

What the session may touch, per minted credential.

promptstring

The session's first message. Omit it and the session starts idle: the sandbox spins up, the agent waits at the prompt, and the first message you send opens turn 0.

repositoriesarray<string>

Repositories to check out in addition to the environment's own, as `owner/name` or a bare `name` (the account's).

skillsarray<SkillRef-Input>

Skills installed for this session.

Response

Example response, 201

{

}

Request

Body parameters

Response

On this page