POST /sessions
Start a cloud agent session.
Provide at most one of config_id (an id or an agent name), config, or template_id; with none, the account's default-config ladder resolves the config. 400 when idle_start is combined with prompt or input. 422 when the agent declares an input schema and the request's input is absent or invalid.
curl -X POST "https://api.ellipsis.dev/v1/sessions" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"..."}'{
"session": {
"agent": {
"config": {
"budget": {
"day": 0,
"month": 0,
"session": 0,
"week": 0
},
"claude": {
"effort": "low",
"fallback_model": "string",
"max_turns": 0,
"model": "claude-opus-5",
"settings": {
"path": "string",
"repository": {}
},
"system": "string"
},
"codex": {
"model": "gpt-5.6-terra",
"system": "string"
},
"ellipsis": {
"description": "string",
"enabled": true,
"interactive": true,
"metadata": {
"annotations": {},
"labels": []
},
"name": "string",
"version": "v1"
},
"environment": {
"compute": {
"cpu": 0,
"memory": "string",
"timeout": "string"
},
"hooks": {
"post_clone": "string",
"post_start": "string"
},
"image": {
"dockerfile_append": "string",
"setup": "string"
},
"repositories": [],
"variables": []
},
"input": {
"json_schema": {},
"message": "string"
},
"mcp_servers": [],
"output": {
"json_schema": {}
},
"permissions": {
"ellipsis": true,
"github": {
"permissions": "string",
"repositories": []
}
},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.start(prompt="...")
print(result){
"session": {
"agent": {
"config": {
"budget": {
"day": 0,
"month": 0,
"session": 0,
"week": 0
},
"claude": {
"effort": "low",
"fallback_model": "string",
"max_turns": 0,
"model": "claude-opus-5",
"settings": {
"path": "string",
"repository": {}
},
"system": "string"
},
"codex": {
"model": "gpt-5.6-terra",
"system": "string"
},
"ellipsis": {
"description": "string",
"enabled": true,
"interactive": true,
"metadata": {
"annotations": {},
"labels": []
},
"name": "string",
"version": "v1"
},
"environment": {
"compute": {
"cpu": 0,
"memory": "string",
"timeout": "string"
},
"hooks": {
"post_clone": "string",
"post_start": "string"
},
"image": {
"dockerfile_append": "string",
"setup": "string"
},
"repositories": [],
"variables": []
},
"input": {
"json_schema": {},
"message": "string"
},
"mcp_servers": [],
"output": {
"json_schema": {}
},
"permissions": {
"ellipsis": true,
"github": {
"permissions": "string",
"repositories": []
}
},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.start({ prompt: '...' });
console.log(result);{
"session": {
"agent": {
"config": {
"budget": {
"day": 0,
"month": 0,
"session": 0,
"week": 0
},
"claude": {
"effort": "low",
"fallback_model": "string",
"max_turns": 0,
"model": "claude-opus-5",
"settings": {
"path": "string",
"repository": {}
},
"system": "string"
},
"codex": {
"model": "gpt-5.6-terra",
"system": "string"
},
"ellipsis": {
"description": "string",
"enabled": true,
"interactive": true,
"metadata": {
"annotations": {},
"labels": []
},
"name": "string",
"version": "v1"
},
"environment": {
"compute": {
"cpu": 0,
"memory": "string",
"timeout": "string"
},
"hooks": {
"post_clone": "string",
"post_start": "string"
},
"image": {
"dockerfile_append": "string",
"setup": "string"
},
"repositories": [],
"variables": []
},
"input": {
"json_schema": {},
"message": "string"
},
"mcp_servers": [],
"output": {
"json_schema": {}
},
"permissions": {
"ellipsis": true,
"github": {
"permissions": "string",
"repositories": []
}
},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}{
"properties": {
"config": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"budget": {
"additionalProperties": false,
"properties": {
"day": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"month": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"session": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"week": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"claude": {
"additionalProperties": false,
"properties": {
"effort": {
"anyOf": [
{
"enum": [
"low",
"medium",
"high",
"xhigh",
"max"
],
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"max_turns": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"model": {
"default": "claude-opus-5",
"type": "string"
},
"settings": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"repository": {
"type": "object"
}
},
"required": [
"path"
],
"type": "object"
},
{
"type": "null"
}
]
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"file": {
"type": "string"
},
"repository": {
"type": "object"
}
},
"required": [
"file"
],
"type": "object"
},
{
"items": {
"type": "object"
},
"type": "array"
}
],
"default": ""
}
},
"type": "object"
},
"codex": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"model": {
"default": "gpt-5.6-terra",
"type": "string"
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array"
}
],
"default": ""
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"ellipsis": {
"additionalProperties": false,
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"default": true,
"type": "boolean"
},
"interactive": {
"default": true,
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"properties": {
"annotations": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"labels": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"version": {
"default": "v1",
"type": "string"
}
},
"type": "object"
},
"environment": {
"additionalProperties": false,
"properties": {
"compute": {
"additionalProperties": false,
"properties": {
"cpu": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"memory": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "null"
}
]
},
"timeout": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"hooks": {
"additionalProperties": false,
"properties": {
"post_clone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"post_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"image": {
"additionalProperties": false,
"properties": {
"dockerfile_append": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"setup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"repositories": {
"default": [],
"items": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"owner": {
"type": "object"
},
"ref": {
"type": "object"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variables": {
"default": [],
"items": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "object"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"input": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"json_schema": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"mcp_servers": {
"default": [],
"items": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
]
},
"type": "array"
},
"output": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"json_schema": {
"additionalProperties": true,
"type": "object"
}
},
"required": [
"json_schema"
],
"type": "object"
},
{
"type": "null"
}
]
},
"permissions": {
"additionalProperties": false,
"properties": {
"ellipsis": {
"anyOf": [
{
"enum": [
true,
"all"
]
},
{
"additionalProperties": {
"anyOf": [
{
"$ref": "#/components/schemas/Level"
},
{
"$ref": "#/components/schemas/EllipsisGrant"
},
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/Level"
},
{
"$ref": "#/components/schemas/EllipsisGrant"
}
]
},
"type": "array"
}
]
},
"propertyNames": {
"$ref": "#/components/schemas/Resource"
},
"type": "object"
}
],
"default": true
},
"github": {
"additionalProperties": false,
"properties": {
"permissions": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "null"
}
]
},
"repositories": {
"anyOf": [
{
"type": "array"
},
{
"type": "null"
}
]
}
},
"type": "object"
}
},
"type": "object"
},
"skills": {
"default": [],
"items": {
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"repository": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"path"
],
"type": "object"
},
"type": "array"
},
"trigger": {
"anyOf": [
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"schedule": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"schedule"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"issue": {
"type": "object"
},
"linear_issue": {
"type": "object"
},
"pull_request": {
"type": "object"
},
"push": {
"type": "object"
},
"sentry": {
"type": "object"
},
"slack_channel": {
"type": "object"
},
"type": {
"type": "string"
}
},
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"platforms": {
"type": "array"
},
"type": {
"type": "string"
}
},
"type": "object"
}
]
},
{
"type": "null"
}
]
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"config_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config_override": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
},
"config_override_yaml": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"force_rebuild": {
"default": false,
"type": "boolean"
},
"idle_start": {
"default": false,
"type": "boolean"
},
"input": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"template_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
}{
"properties": {
"session": {
"properties": {
"agent": {
"properties": {
"config": {
"additionalProperties": false,
"properties": {
"budget": {
"additionalProperties": false,
"properties": {
"day": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"month": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"session": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"week": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"claude": {
"additionalProperties": false,
"properties": {
"effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"max_turns": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"model": {
"default": "claude-opus-5",
"type": "string"
},
"settings": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array"
}
],
"default": ""
}
},
"type": "object"
},
"codex": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"model": {
"type": "string"
},
"system": {
"type": "object"
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"ellipsis": {
"additionalProperties": false,
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"default": true,
"type": "boolean"
},
"interactive": {
"default": true,
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"properties": {
"annotations": {
"type": "object"
},
"labels": {
"type": "array"
}
},
"type": "object"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"version": {
"default": "v1",
"type": "string"
}
},
"type": "object"
},
"environment": {
"additionalProperties": false,
"properties": {
"compute": {
"additionalProperties": false,
"properties": {
"cpu": {
"type": "object"
},
"memory": {
"type": "object"
},
"timeout": {
"type": "object"
}
},
"type": "object"
},
"hooks": {
"additionalProperties": false,
"properties": {
"post_clone": {
"type": "object"
},
"post_start": {
"type": "object"
}
},
"type": "object"
},
"image": {
"additionalProperties": false,
"properties": {
"dockerfile_append": {
"type": "object"
},
"setup": {
"type": "object"
}
},
"type": "object"
},
"repositories": {
"default": [],
"items": {
"type": "object"
},
"type": "array"
},
"variables": {
"default": [],
"items": {
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"input": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"json_schema": {
"type": "object"
},
"message": {
"type": "object"
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"mcp_servers": {
"default": [],
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
}
]
},
"type": "array"
},
"output": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"json_schema": {
"type": "object"
}
},
"required": [
"json_schema"
],
"type": "object"
},
{
"type": "null"
}
]
},
"permissions": {
"additionalProperties": false,
"properties": {
"ellipsis": {
"anyOf": [
{
"type": "object"
},
{
"type": "object"
}
],
"default": true
},
"github": {
"additionalProperties": false,
"properties": {
"permissions": {
"type": "object"
},
"repositories": {
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"skills": {
"default": [],
"items": {
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"repository": {
"type": "object"
}
},
"required": [
"path"
],
"type": "object"
},
"type": "array"
},
"trigger": {
"anyOf": [
{
"oneOf": [
{
"type": "object"
},
{
"type": "object"
},
{
"type": "object"
}
]
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"config_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"override": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"explicit",
"inline",
"template",
"repo_default",
"account_default",
"platform_default",
"trigger",
"builtin"
],
"type": "string"
}
},
"required": [
"config",
"source"
],
"type": "object"
},
"attribution": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"anyOf": [
{
"enum": [
"github_user",
"linear_user",
"slack_user",
"api_key"
],
"type": "string"
},
{
"type": "null"
}
]
},
"user": {
"anyOf": [
{
"properties": {
"avatar_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"login": {
"type": "string"
},
"type": {
"enum": [
"User",
"Organization",
"Bot",
"Mannequin"
],
"type": "string"
}
},
"required": [
"id",
"login",
"type",
"avatar_url"
],
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"budget": {
"properties": {
"cents": {
"default": 0,
"type": "integer"
},
"source": {
"enum": [
"system",
"account",
"config",
"run"
],
"type": "string"
}
},
"type": "object"
},
"context_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cost": {
"properties": {
"fee": {
"default": 0,
"type": "integer"
},
"llm": {
"default": 0,
"type": "integer"
},
"sandbox_cpu": {
"default": 0,
"type": "integer"
},
"sandbox_memory": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"exit_status": {
"anyOf": [
{
"enum": [
"completed",
"budget_hit",
"payment_required",
"tool_call_failed",
"lifecycle_hook_failed",
"missing_repo_access",
"missing_token_permissions",
"missing_sandbox_variables",
"blocked",
"contact_email_required",
"cancelled",
"interrupted",
"error",
"stopped"
],
"type": "string"
},
{
"type": "null"
}
]
},
"git": {
"anyOf": [
{
"properties": {
"repos": {
"default": [],
"items": {
"properties": {
"full_name": {
"type": "string"
},
"local_commit": {
"type": "object"
},
"local_uncommitted_files": {
"type": "array"
},
"prs": {
"type": "array"
},
"remote_branch": {
"type": "object"
},
"remote_commit": {
"type": "object"
}
},
"required": [
"full_name"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"harness": {
"enum": [
"claude_code",
"codex"
],
"type": "string"
},
"id": {
"type": "string"
},
"last_activity_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"last_message_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"parent": {
"properties": {
"kind": {
"anyOf": [
{
"enum": [
"continuation",
"resume"
],
"type": "string"
},
{
"type": "null"
}
]
},
"replayed_from_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prompting": {
"properties": {
"blocked_reason": {
"anyOf": [
{
"enum": [
"mention_surface",
"ephemeral_trigger",
"non_interactive",
"harness_single_turn",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"surface_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"enabled"
],
"type": "object"
},
"session_state": {
"anyOf": [
{
"enum": [
"idle",
"running",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"react",
"manual",
"api",
"cli",
"mention",
"cron"
],
"type": "string"
},
"status": {
"enum": [
"scheduled",
"creating_sandbox",
"running",
"retrying",
"completed",
"error",
"cancelled",
"stopped"
],
"type": "string"
},
"status_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"stopped": {
"properties": {
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"by": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"by_user": {
"anyOf": [
{
"properties": {
"avatar_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"login": {
"type": "string"
},
"type": {
"enum": [
"User",
"Organization",
"Bot",
"Mannequin"
],
"type": "string"
}
},
"required": [
"id",
"login",
"type",
"avatar_url"
],
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"summary": {
"anyOf": [
{
"properties": {
"created_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"type": "string"
}
},
"required": [
"description"
],
"type": "object"
},
{
"type": "null"
}
]
},
"surface": {
"anyOf": [
{
"properties": {
"run": {
"anyOf": [
{
"enum": [
"scheduled",
"starting",
"working",
"waiting",
"done",
"failed",
"stopped",
"cancelled",
"retrying"
],
"type": "string"
},
{
"type": "null"
}
]
},
"session": {
"anyOf": [
{
"enum": [
"alive",
"sleeping",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"session",
"run",
"status"
],
"type": "object"
},
{
"type": "null"
}
]
},
"tokens": {
"properties": {
"cache_creation": {
"default": 0,
"type": "integer"
},
"cache_read": {
"default": 0,
"type": "integer"
},
"input": {
"default": 0,
"type": "integer"
},
"model": {
"default": "",
"type": "string"
},
"output": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"created_at",
"updated_at",
"harness",
"source",
"status",
"prompting",
"agent"
],
"type": "object"
}
},
"required": [
"session"
],
"type": "object"
}Request
configAgentConfig
An inline agent config to run under.
config_idstring
A saved agent config to run under: its id, or the agent's customer-unique `ellipsis.name`.
config_overrideobject
Optional partial-config override merged onto the chosen config and re-validated (e.g. {"budget": {"session": 5.0}} to raise just this session's budget). Merged onto config_id/template_id or the platform default; with an inline config, set fields directly instead. Mutually exclusive with config_override_yaml.
config_override_yamlstring
The same partial-config override as a YAML/JSON string (e.g. read from a file). Mutually exclusive with config_override.
force_rebuilddefault
falsebooleanSkip the image cache for this session's initial provision: a fresh full build whose snapshot then refreshes the cache for later runs. A wake of a durable session provisions through the cache as usual. The CLI's `--rebuild`.
idle_startdefault
falsebooleanStart the session with no initial message: the sandbox spins up, the agent starts idle at the prompt, and the first message sent to the session opens turn 0. Mutually exclusive with prompt. Ignored when the resolved config is not interactive (an ephemeral run keeps its kickoff — it can never receive a message).
inputobject
The typed payload for an agent that declares input.json_schema: validated against the effective config's schema (422 on mismatch), rendered into the session's initial message (the agent's input.message template, or a JSON block). Required when the agent declares a schema; rejected when it does not.
metadatadefault
{}objectArbitrary string key/value metadata stored on the session.
promptstring
Per-run instructions appended to the initial query after the config's shared system prompt. Applies regardless of which config source is used.
repositorystring
The "owner/name" repository the client is standing in (the CLI's detected git remote). Selects the repo rung of the defaults ladder, and is merged into the sandbox repository set (cloned at its default branch) regardless of which config source is used. An unknown or foreign repo is ignored.
template_idstring
A maintained run-on-demand template slug (e.g. "ellipsis-helper"), resolved server-side to its config. At most one of config_id, config, or template_id may be set; if none is, the run resolves the account's default-config ladder (repo default, then account default, then the platform default config).