---
title: "Capture a screenshot of a remote desktop machine"
method: GET
path: "/api/v1/screenshot/{code}"
---

# Capture a screenshot of a remote desktop machine

`GET /api/v1/screenshot/{code}`

## Request

- Base URL: `https://aicommander.dev`
- URL: `https://aicommander.dev/api/v1/screenshot/{code}`
- Auth: one of:
  - none
  - HTTP bearer

Returns the machine's PRIMARY display as an image (macOS/Windows desktop app only). `code` may be an AIC- session code OR (with an API key) a saved alias/hostname like 'wearfits-m3'. Selecting a different monitor, and the capture metadata naming which display you got, exist on the MCP tool only — a raw image response has nowhere to put a caption — so this endpoint always returns the primary screen on a multi-monitor machine.

TWO THINGS MUST BOTH BE TRUE, and on macOS they are separate. (1) Screen sharing is OFF by default and must be enabled by the owner in the AI Commander tray ('Share Screen'); the grant lasts 24 hours then auto-disables. (2) On macOS the operating system's own Screen Recording permission must also be granted to AI Commander in System Settings ▸ Privacy & Security ▸ Screen Recording. The tray toggle does NOT grant it: macOS asks in a dialog on that machine, so on an unattended machine nobody is there to click Allow and every capture fails or comes back blank. GET /api/v1/status/{code} reports both — check it first. When either is missing, the machine is a headless Linux server, or the agent is offline, this returns a JSON error (403/503) rather than an image. Images are capped at 10 MB.

## Path parameters

- `code` string, required

## Response `200`

The screenshot image bytes.

## Other responses

- `401`: A token was supplied but is not a valid API key/admin/OAuth token.
- `403`: Resolved but refused. Causes include expired anonymous access; Free/anonymous file transfer; `reason: plan_device_limit`; independent operator block/approval; or `error: reactivation_required`. For plan_device_limit, delete an older saved machine to promote the next or upgrade to Pro. For file transfer, use Pro. Do not conflate either with operator approval.
- `404`: Session code or alias not found (anonymous callers get a unified message that does not confirm existence).
- `429`: Per-IP or global tool-call rate limit exceeded.
- `503`: The session exists but the agent is offline or disconnected mid-command.

---

[API](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api.md) · [All operations](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api/revisions/a6bb89f779a1?raw)