Recamera Web API

reCamera Web API

Complete API reference for the reCamera (RV1126B) embedded camera platform. This skill enables agents to correctly construct HTTP requests, handle responses, and follow the interaction protocols required by the device.

Conventions

Base URL

All CGI endpoints are prefixed with:

/cgi-bin/entry.cgi/{api_category}/{resource}/{sub_resource}

Exceptions clearly noted per-endpoint (e.g. serial port uses /api/v1/..., file relay uses /storage/relay/...).

Authentication (CRITICAL — Token Must Be Captured and Reused)

Login flow (mandatory for all authenticated operations):

1. Fetch RSA public key: GET /system/key (no auth required)
2. Login: POST /system/login with {sUserName, sPassword} (password RSA-encrypted)
3. Extract token from response: On success (iStatus: 0, iAuth: 1), the HTTP response contains a Set-Cookie header like Set-Cookie: token=<jwt_value>; Path=/; .... You MUST capture the token value from this header.
4. Persist token for session: Store the extracted token value. All subsequent HTTP requests for this session must include the header: Cookie: token=<jwt_value>

For curl / shell scripts:

# Login and capture token from Set-Cookie header
RESPONSE=$(curl -s -D - -X POST http://{ip}/cgi-bin/entry.cgi/system/login \
  -H "Content-Type: application/json" \
  -d '{"sUserName":"admin","sPassword":"<RSA-encrypted>"}')
TOKEN=$(echo "$RESPONSE" | grep -oP 'Set-Cookie:.*token=\K[^;]+')

# ALL subsequent requests must carry the token cookie
curl -s -X GET http://{ip}/cgi-bin/entry.cgi/system/device-info \
  -H "Cookie: token=$TOKEN"

For browser automation (browser-use agent): After navigating to the login page and submitting credentials, the browser automatically stores the token cookie from the Set-Cookie header. However, you should verify the cookie exists by checking document.cookie for a token= entry after login succeeds. All subsequent same-origin XHR/fetch requests will include the cookie automatically (the app uses withCredentials: true).

IMPORTANT: If you receive an HTTP 401 response or a response body with "code": 401, the token has expired or is missing. You must re-login to obtain a fresh token.

Agent Playbooks (Mandatory Execution)

When user intent matches one of the following tasks, execute the corresponding workflow directly.

Playbook A: Discover reCamera Devices in a Subnet

Trigger intent examples: "scan subnet", "find recamera on 192.168.x.0/24", "discover devices in LAN"

Mandatory workflow:

1. Enumerate active IPs in the target subnet (e.g. ARP table / ping sweep / nmap host discovery).
2. For each active IP, send GET http://{ip}/cgi-bin/entry.cgi/system/key (no auth).
3. Classify as reCamera only if:
   • HTTP status is 200, and
   • response contains field sPublicKey.
4. Return a structured result with:
   • reachable_ips
   • recamera_ips
   • non_recamera_ips
   • unreachable_or_timeout_ips

Do not treat "TCP port open" alone as reCamera confirmation. /system/key verification is required.

Playbook B: Login and Persist Token for Follow-up Calls

Trigger intent examples: "login device", "call authenticated API", "configure after login"

Mandatory workflow:

1. GET /system/key to fetch RSA public key.
2. POST /system/login with {sUserName, sPassword} (RSA-encrypted password).
3. On successful login (iStatus: 0, iAuth: 1), parse Set-Cookie response header and extract token.
4. Persist token in session context.
5. For all subsequent HTTP requests in the same session, include:
   • Cookie: token=<jwt_value>
6. If any request returns 401 / auth failure, re-login and refresh token, then retry once.

Do not continue authenticated calls without a captured token.

Configuration Update Pattern (Read-Before-Write)

CRITICAL: For any endpoint that supports both GET and POST/PUT:

1. First GET the current full configuration
2. Modify only the fields you need to change on the returned data
3. POST/PUT the complete modified configuration back

Never send a partial configuration constructed from scratch. The device expects the full config object and omitted fields may revert to defaults or cause unexpected behavior.

Field Naming

JSON keys use a type-prefix + camelCase convention:

Standard Response

Operation endpoints (POST/PUT/DELETE) return:

{
  "code": 0,
  "message": "success"
}

code: 0 = success. Non-zero = error (see error code ranges below).

Error Code Ranges

API Quick Reference

1. Authentication

Login response key fields:

• iStatus: 0=correct, -1=wrong password, -3=rate limited
• iAuth: 1=success, 0=fail, 2=must change password

2. Device Info

3. Live Video

stream_id: 0=main stream, 1=sub stream

4. Image (ISP) Settings

scene_id: 0=general, 1=day, 2=night

ISP Configuration Workflow:

1. GET /image/0 — fetch all params and determine current scene/profile in use
2. Select target scene profile (scene_id / iProfile: 0|1|2) based on current mode or user-specified mode
3. PUT /image/0/scene with {iProfile: 0|1|2} — enter that profile's live edit mode (5min timeout)
4. Adjust parameters (brightness/contrast/hue/saturation/sharpness etc.) via PUT /image/0/{scene_id}/{specific}
5. Send save/commit command: PUT /image/0/scene with {iProfile: -1} to exit edit mode and finalize changes

Mandatory sequence for image tuning tasks: "select mode -> enter mode edit state -> adjust params -> send save command". Do not skip the final save/commit step.

5. Recording

Trigger types: INFERENCE_SET, TIMER, GPIO, TTY, HTTP

Storage control actions: FORMAT, FREE_UP, EJECT, CONFIG, RELAY, RELAY_STATUS, UNRELAY, REMOVE_FILES_OR_DIRECTORIES