Reference
media
Screenshots and screen recordings. Index · shared schemas · errors.
| Procedure | Summary | REST | MCP tool | Stability |
|---|---|---|---|---|
media.screenshot | Capture the screen, or one element's frame (MCP returns image content) | POST | media_screenshot | stable |
media.startRecording | Start an MP4 recording of the device stream | POST | — | stable |
media.stopRecording | Stop a recording and return the file | POST | — | stable |
media.screenshot
Capture the screen, or one element's frame (MCP returns image content)
| REST | POST /v1/media/screenshot (input as a JSON body) |
| RPC | /rpc/v2/media/screenshot |
| MCP | tool media_screenshot; hints: read-only, idempotent |
| Auth | devices:read |
| Tenancy | project |
| Requires | media.screenshot |
| Troupe Cloud | relayed through the host agent to the device host’s runtime |
| Stability | stable, since 1.0 |
Input:
{
sessionId: SessionId
format?: 'png' | 'jpeg' // default 'png'
quality?: integer // 1–100
target?: Target
}Output: a binary body, image/png or image/jpeg (the raw response body with its Content-Type).
Errors: S, DEVICE_MEDIA_FAILED, LOCATOR_NOT_FOUND, LOCATOR_STRICT_VIOLATION, LOCATOR_REF_STALE.
Named types: SessionId, Target.
media.startRecording
Start an MP4 recording of the device stream
| REST | POST /v1/media/start-recording (input as a JSON body) |
| RPC | /rpc/v2/media/startRecording |
| MCP | not a tool (part of the recording flow, which returns a file); hints: none |
| Auth | devices:read |
| Tenancy | project |
| Requires | media.recording |
| Troupe Cloud | relayed through the host agent to the device host’s runtime |
| Stability | stable, since 1.0 |
Input:
{
sessionId: SessionId
maxDurationMs?: integer // default 600000; 1000–3600000
}Output:
{ recordingId: RecordingId; startedAt: string }Errors: S, CONFLICT, DEVICE_MEDIA_FAILED.
Named types: RecordingId, SessionId.
media.stopRecording
Stop a recording and return the file
| REST | POST /v1/media/stop-recording (input as a JSON body) |
| RPC | /rpc/v2/media/stopRecording |
| MCP | not a tool (part of the recording flow, which returns a file); hints: none |
| Auth | devices:read |
| Tenancy | project |
| Requires | media.recording |
| Troupe Cloud | relayed through the host agent to the device host’s runtime |
| Stability | stable, since 1.0 |
Input:
{ sessionId: SessionId; recordingId: RecordingId }Output:
{ recordingId: RecordingId; durationMs: number; file: FileRef }Errors: S, DEVICE_MEDIA_FAILED.
Named types: FileRef, RecordingId, SessionId.