# POST /v1/sessions/{session_id}/screen

> With the session's token, in control mode: the user takes the wheel or gives it back (action), or says they are driving (input), so Bash waits.

In [Sessions API](https://vestra.ai/developers/reference/api/sessions.md): Bash in a browser: its live screen, a voice call, or the whole of Bash inside your app.

Send `Authorization: Bearer vk_test_...` on every call.

With the session's token, in control mode: the user takes the wheel or gives it back (action), or says they are driving (input), so Bash waits.

A session's token. On the card: [`watch`](https://vestra.ai/developers/watch.md). Every call here is a checked sample.

## Request

Path:

- `session_id` (`string`, required): The session's id (`ses_...`).

Body:

Either `{ action }`:

- `action` (`"take" | "give_back"`, required): take: the person takes the wheel and Bash waits. give_back: Bash drives again.

Or `{ input }`:

- `input` (`true`, required): The person is typing or clicking now: Bash holds off while these keep coming, each good for a few seconds.

## Answers 200

Either `{ object, by }`:

- `object` (`"screen_control"`): Always screen_control.
- `by` (`"user" | "bash"`): Who drives the screen now: user, the person, or bash.

Or `{ object, delivered }`:

- `object` (`"screen_input"`): Always screen_input.
- `delivered` (`boolean`): Whether Bash's computer heard it; false when it is not connected.

## Code

**TypeScript**

```ts
const session = await vestra.user('traveller-42').watch({ control: true });
await session.take();
```

**Python**

```python
session = vestra.user("traveller-42").watch(control=True)
session.take()
```

**HTTP**

```bash
# Watch the screen live. Create a session with a screen to watch, and open its url in a browser tab or an iframe.
curl "$VESTRA_BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "screen": "view" }'

# Let a person take control. In a session opened with "screen": "control", the person can take over from Bash,
# using the session's own token.
curl "$VESTRA_BASE_URL/v1/sessions/ses_8h2/screen" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "take" }'

# Take a screenshot. You get the latest frame of the user's browser as a JPEG.
curl "$VESTRA_BASE_URL/v1/users/traveller-42/screenshot" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -o screen.jpg
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "watch",
    "arguments": { "user": "traveller-42", "control": true }
  }
}
```

**CLI**: No sample in your language for this route, so here it is over HTTP.