MASAKA / Get started / Quickstart
Quickstart

Create, inspect,
and stop.

This walkthrough uses the REST contract directly so every SDK and Agent Harness integration has the same ground truth.

1. Create a project key

Sign in, open Dashboard → API keys, and save the key once as MASAKA_API_KEY in trusted server configuration.

2. Create a bounded session

cURL
curl https://masaka-backend.vercel.app/api/sessions \
  -H "Authorization: Bearer $MASAKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Quickstart","url":"https://example.com/","region":"overseas","preview_mode":"visual","max_seconds":180}'

Persist the returned session ID. Poll GET /api/sessions/:id with backoff until its status is running.

3. Acquire control and observe

POST/api/sessions/:id/control{"mode":"agent"}
POST/api/sessions/:id/commands{"kind":"snapshot"}

The snapshot result includes page content plus tabs and active_tab. Use returned handles for tab operations; never guess one.

Tab switch
POST /api/sessions/:id/commands
{"kind":"tabs"}

POST /api/sessions/:id/commands
{"kind":"tab_switch","handle":"<handle returned above>"}

4. Stop in guaranteed cleanup

POST/api/sessions/:id/stopIdempotent terminal request

Poll the session to a terminal state when your process needs confirmed accounting. Explicit stop, timeout, startup failure, expiration, and worker loss all converge on settlement.