Sessions

Sessions

Sessions endpoints of the Ellipsis REST API.

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

{

}

Method	Path	Required permissions
GET	/v1/sessions	read: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.

Query parameters

automationstring

An automation id, or its name: only sessions that automation started.

sourcearray<SessionSource>

serviceenum

Service that triggered the session. Includes built-in responders and legacy sessions without a saved handler.

one ofslackgithublinearsentry

handlerstring

Saved handler id captured when the session started.

daysinteger

startstring, date-time

endstring, date-time

limitdefault 50integer

cursorstring

author_idinteger

A GitHub account id (see GET /v1/integrations/github/members); scopes the list to sessions attributed to that developer.

repostring

"owner/name" (exact) or a bare repo name. Sessions whose repository is named only inside their automation , dashboard starts, cron , do not match.

unfinisheddefault falseboolean

Keep only sessions whose conversation is still going , live or idle , dropping the ones that completed, errored, or were stopped or cancelled. A session parked between turns counts as unfinished.

exclude_code_reviewdefault falseboolean

curl "https://api.ellipsis.dev/v1/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

for await (const item of await client.sessions.list()) {
  console.log(item);
}

Request

Response

Example response, 200

{

"has_more": false,

"next_cursor": "string",

"pull_requests": {},

"turn_counts": {}

}

Method	Path	Required permissions
GET	/v1/sessions/search	read: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.

Supply q and filter by service, handler, or source.

Query parameters

qstringrequired

scopeenum

What text a search query is matched against: the session log's record text, the session recaps (summaries), or both.

one ofrecordsrecapsboth

sourcearray<SessionSource>

serviceenum

Service whose mention or event started the session.

one ofslackgithublinearsentry

handlerstring

Exact saved handler id recorded when the session started.

author_idarray<integer>

Attributed GitHub user account ids.

automation_idarray<string>

Saved automation ids (ORed with author_id).

session_idsarray<string>

repoarray<string>

"owner/name" (exact) or a bare repo name; ORed.

statusarray<SessionStatus>

startstring, date-time

endstring, date-time

limitdefault 20integer

curl "https://api.ellipsis.dev/v1/sessions/search?q=..." \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.search({ q: "validation" });
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}	read: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.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.get("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/diff	read: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. Only the token's own session.

Higher permission levels include lower levels: read < write < delete.

Grant match patterns can further restrict access to individual resources.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/diff" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.diff("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/executions	read: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.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/executions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.executions("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/export	read: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.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/export" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.export("session_example");
console.log(result);

Request

Response

Example response, 200

{

"archived_through_feed_seq": 0,

"earliest_feed_seq": 0,

"format": "ellipsis_session_log@1",

"has_more": false,

"latest_feed_seq": 0,

"session_id": "string"

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/git	read: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.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/git" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.git("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
POST	/v1/sessions/{session_id}/messages	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.

Messages received during a turn wait for the next turn. Reuse an idempotency key when retrying the same message.

Path parameters

session_idstringrequired

curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/messages" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Add a regression test.",
  "idempotency_key": "add-test"
}'

import os

from ellipsis import Ellipsis
from ellipsis import models

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

request = models.SendSessionMessageRequest.model_validate(
    {
      "message": "Add a regression test.",
      "idempotency_key": "add-test"
    }
)

result = client.sessions.send_message(
    "session_example",
    request.message,
    idempotency_key=request.idempotency_key,
)
print(result)

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

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

const request: Parameters<typeof client.sessions.sendMessage>[1] = {
  "message": "Add a regression test.",
  "idempotency_key": "add-test"
};

const result = await client.sessions.sendMessage("session_example", request);
console.log(result);

Request

Example request body

{

"message": "Add a regression test.",

"idempotency_key": "add-test"

}

Body parameters

idempotency_keystring

Optional retry-safety key, unique per (session, key): a retry with the same key returns the original message , no duplicate message, no double turn, no double spend. The SDK auto-generates one per send.

imagesarray<ImageAttachment>

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

messagestringrequired

The message text. May be empty when `images` is not.

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/output	read: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.

Path parameters

session_idstringrequired

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/output" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.output("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

Method	Path	Required permissions
GET	/v1/sessions/{session_id}/records	read: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.

Partial text deltas are live-only.

Path parameters

session_idstringrequired

Query parameters

cursorstring

limitinteger

curl "https://api.ellipsis.dev/v1/sessions/{session_id}/records" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

for await (const item of await client.sessions.records("session_example")) {
  console.log(item);
}

Request

Response

Example response, 200

{

"earliest_feed_seq": 0,

"has_more": false,

"messages": [],

"next_cursor": "string",

}

Method	Path	Required permissions
POST	/v1/sessions/{session_id}/stop	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.

Its recorded history remains available.

Path parameters

session_idstringrequired

curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/stop" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

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

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

const result = await client.sessions.stop("session_example");
console.log(result);

Request

Response

Example response, 200

{

}

POST /v1/sessions GET /v1/sessions GET /v1/sessions/search GET /v1/sessions/{session_id}GET /v1/sessions/{session_id}/diff GET /v1/sessions/{session_id}/executions GET /v1/sessions/{session_id}/export GET /v1/sessions/{session_id}/git POST /v1/sessions/{session_id}/messages GET /v1/sessions/{session_id}/output GET /v1/sessions/{session_id}/records POST /v1/sessions/{session_id}/stop

Schedule a demo

Request

Body parameters

Response

Query parameters

Request

Response

Query parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Body parameters

Response

Path parameters

Request

Response

Path parameters

Query parameters

Request

Response

Path parameters

Request

Response

On this page