Docs/AgentEyes/Control API
AgentEyes

The AgentEyes Control API

4 min read

The running AgentEyes app serves a local REST Control API so a script or an agent can drive the recorder without touching the tray window - read what it is doing, start and stop recordings, take screenshots, and run import, translate, and subtitle. It is the same engine the app uses, exposed over plain JSON.

Address and scope

The API binds to 127.0.0.1:7882 only - the loopback address. It is reachable from the machine it runs on and nowhere else; nothing it does crosses the network. GET / returns a discovery document that lists every endpoint, and GET /health and GET /version confirm it is up.

Note
Loopback-only is the boundary: anything that can run code on your PC can drive the recorder, which is the point for local automation. Recording, screenshots, and subtitle burning stay on the machine. Import and translate reach out to DevThrottle's hosted AI to transcribe and translate - see Import a video.

Read state

GET/status
What the recorder is doing right now.
GET/devices
Available monitors and microphones.
GET/presets
The saved capture presets.
GET/recordings
The recording library, newest first. Add ?limit= and ?offset= to page. GET /recordings/{id} fetches one (with the languages it carries), GET /recordings/{id}/shots lists its screenshots, and GET /recordings/{id}/transcript returns its transcript.
GET/captures
The screenshot gallery.

Record and capture

POST/record/start
Start a recording. A preset name supplies the defaults; explicit fields override them. Fields: preset?, mode, screen, source, mic?, region?, denoise?, gate?, level?, micVol?, sysVol?, fps?.
POST/record/shot
Take a screenshot during the current recording.
POST/record/stop
Stop the recording; it is finalized and transcribed in the background.
POST/screenshot
Take a screenshot outside a recording. Body: { "screen": 1, "region": [x,y,w,h] } (region optional).
POST/capture
Capture to the save folder and clipboard. Body: { "mode": "full" | "monitor" | "region", "screen"?, "region"? }.
POST/dictate
Trigger voice typing (returns 503 if dictation is disabled).

Import, translate, subtitle

POST/import
Import an external video into the library. Body: { "path": "C:/.../video.mp4" }. Synchronous; returns the new recording id and dir.
POST/transcripts/{id}/translate
Translate the recording's transcript. Body: { "to": "tr" }. Returns language, cues, and the vtt file name.
POST/recordings/{id}/subtitle
Burn a language's captions into a new video. Body: { "language": "tr" }. Returns the output file name.

Example

Import a video, then caption it in Turkish
# 1) import - returns { "id": "...", "dir": "..." }
curl.exe -s -X POST http://127.0.0.1:7882/import \
  -H "Content-Type: application/json" \
  --data-binary "{ \"path\": \"C:/Users/me/Videos/Weekly sync.mp4\" }"

# 2) translate the transcript into Turkish
curl.exe -s -X POST http://127.0.0.1:7882/transcripts/<id>/translate \
  -H "Content-Type: application/json" \
  --data-binary "{ \"to\": \"tr\" }"

# 3) burn the Turkish captions into a new video
curl.exe -s -X POST http://127.0.0.1:7882/recordings/<id>/subtitle \
  -H "Content-Type: application/json" \
  --data-binary "{ \"language\": \"tr\" }"
Note
Errors come back as a small JSON envelope - { "error": "...", "code": "..." } - with a matching HTTP status: 400 for bad input, 404 for an unknown recording, 409 for a lifecycle conflict such as starting a recording while one is already running.

Where to go next

For one-off commands rather than driving a running app, see the CLI reference. For the features these endpoints expose, see Import a video and Multilingual subtitles.