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 the loopback address, 127.0.0.1:7882 by default (the port is configurable, and the API can be turned off entirely). That binding decides who can CALL it: the machine it runs on, and nowhere else. It does not decide what the calls then do - some of them send data outward, and which ones is the next paragraph. GET / returns a discovery document that lists every endpoint, and GET /health and GET /version confirm it is up.

Note

Two separate boundaries, and it is worth keeping them apart. Who can reach the API is loopback-only - which also means anything that can run code on your PC can drive the recorder, and that is the point for local automation. What a call does varies by endpoint: recording, screenshots and subtitle burning stay on the machine, while /import and the translate step send your audio and text to DevThrottle's hosted AI to be transcribed and translated - see Import a video. A call arriving over loopback is not a promise that it stays there.

Read state

GET/status

What the recorder is doing right now.

GET/devices

Available monitors, microphones, and the cameras a recording can film. A machine with no camera answers with an empty cameras array - that is a fact about the machine, not an error.

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.

GET/capture-info

Where snips are saved: the Windows default folder, the override you configured (or null), and the folder actually in use.

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?, camera?, cameraFps?, 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"? }.

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.