Request a new browser session

POST

/api/v1/browser-sessions

curl --request POST \
  --url https://api.ultimateteam.ai/api/v1/browser-sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "agent_role": "example", "estimated_cost_usd": 0, "target_url": "example", "task": "example", "tier": "research" }'

• Production
• Local development

Requests a new browser session for the specified agent and tier. Research and account tiers start immediately; payment tier requires human approval.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

CreateSessionRequest

Request body for creating a new browser session.

Attributes: agent_role: Which C-suite agent is requesting the session. task: Description of the browsing objective. target_url: Starting URL for the session. tier: Autonomy tier (research, account, payment). estimated_cost_usd: Estimated cost for budget tracking.

object

agent_role

required

Agent Role

string

estimated_cost_usd

Estimated Cost Usd

number

0

target_url

required

Target Url

string

task

required

Task

string

tier

required

SessionTier

Browser session autonomy tiers.

Controls URL allowlist enforcement and approval routing:

• research: read-only browsing, any URL, no approval
• account: create accounts / accept ToS, pre-approved domains
• payment: purchases with virtual card, requires human approval

string

Allowed values: research account payment

Responses

201

Successful Response

Media typeapplication/json

BrowserSessionResult

Result returned after a browser session lifecycle event.

Returned by request_session(), on_approval(), and complete_session() to give callers the current state.

Attributes: session_id: Unique session identifier. status: Current lifecycle status. approval_id: AutonomyEngine approval request ID (payment tier). recording_gcs_path: GCS path to rrweb recording JSON. summary: Structured session summary. screenshots: List of GCS screenshot paths. credits_consumed: Credits used during the session. duration_ms: Session duration in milliseconds. error_message: Error description if session failed.

object

approval_id

Any of:

string

string

null

null

credits_consumed

Credits Consumed

integer

0

duration_ms

Any of:

integer

integer

null

null

error_message

Any of:

string

string

null

null

recording_gcs_path

Any of:

string

string

null

null

screenshots

Screenshots

Array<string>

session_id

required

Session Id

string format: uuid

status

required

SessionStatus

Lifecycle states for a browser session.

string

Allowed values: pending approved running completed failed timeout

summary

Any of:

object

object

key

additional properties

any

null

null

Example

{
  "credits_consumed": 0,
  "status": "pending"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}