Run an agent

POST /v1/agents/{agent_id}/sessions

Permission: write:sessions
Tokens: API key, CLI user token, Sandbox token

Start a one-shot session from a saved Claude Code agent. Supply input when it declares an input schema; otherwise supply prompt. Send exactly one.

Path parameters

agent_idstringrequired

{

"budget": float,

"prompt": str

}

import os

from ellipsis import Ellipsis
from ellipsis import models

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

request = models.StartAgentSessionRequest.model_validate(
    {
      "prompt": "Run the tests."
    }
)

result = client.agents.run("check-tests", 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.agents.run>[1] = {
  "prompt": "Run the tests."
};

const result = await client.agents.run("check-tests", request);
console.log(result);

curl -X POST "https://api.ellipsis.dev/v1/agents/{agent_id}/sessions" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Run the tests."
}'

Request

budgetnumber

Tighten this run's spend cap, in US dollars. May only lower the agent's own session budget; a higher number, or one above the organization's ceiling, is a 400.

inputobject

The typed payload for an agent that declares input.json_schema. Required when the agent declares a schema; rejected when it does not. Validated against the schema and rendered through input.message, or as formatted JSON if no template is set. The rendered message must be non-empty. Cannot be combined with prompt.

metadatadefault {}object

Arbitrary string key/value metadata stored on the session.

promptstring

The initial user message, passed verbatim to Claude. Required when the agent declares no input.json_schema; rejected when it does. Must contain non-whitespace text and cannot be combined with input.

Response

sessionSessionrequired

The session.

Path parameters

Request

Response

On this page