jasonk/Reolink API.md

## Reolink API.md

      
    Raw
  

              Reolink API.md
            
          
    Reolink API Examples

I had some difficulty finding simple examples of how to use the Reolink API and ended up digging through some python implementations to figure out how it works.
The official documentation is available at https://bit.ly/3rWxG6e but it is a bit lacking, and the API is somewhat weird, which makes it difficult.  You should still look at it though, as it lets you know what commands are available through the API.
The main weirdness is that even if you are sending one command at a time, the payload has to be an array of objects and the response is always an array of objects.  Also, you have to pass the command both as a URL parameter and in the payload.
Included here are a small(ish) bash script (also requires jq) for running API commands against Reolink cameras or NVRs.

  
## rl-api
#!/bin/bash

HOST="$REOLINK_NVR_HOST" # Your NVR or Camera IP Address
USER="$REOLINK_NVR_USER" # Your username
PASS="$REOLINK_NVR_PASS" # Your password
# Set this to true and the script will dump the request/response
# payloads to stderr.
DEBUG=false

### END OF CONFIGURATION ###

URL="https://$HOST/cgi-bin/api.cgi"

# TOKEN must initially be set to null, so that it gets passed to the
# login command as `?cmd=Login&token=null`
TOKEN="null"

# Takes an API command as the first argument, and JSON-ish payload as
# an optional second argument.  If a payload is provided it's
# processed with `jq -n` to make it easier (jq -n doesn't require
# property names to be quoted, you can have trailing commas and other
# stuff that isn't actually valid JSON)
rl-api() {
  local CMD="$1" PARAM='{}'
  if [ -n "$2" ]; then PARAM="$(jq -n "$2")"; fi
  local REQ="$(
    jq -n --arg CMD "$CMD" --argjson PARAM "$PARAM" '{
      cmd: $CMD,
      action: 0,
      param: $PARAM,
    }'
  )"
  local TGT="$URL?cmd=$CMD&token=$TOKEN"
  if $DEBUG; then
    echo ">>> REQUEST >>>" 1>&2
    echo "TARGET: $TGT" 1>&2
    jq -C . <<<"$REQ" 1>&2
  fi
  local RES="$(
    curl -kfsSLH 'Content-Type: application/json' -d "[$REQ]" -XPOST "$TGT" |
      jq '.[0]'
  )"
  if $DEBUG; then
    echo "<<< RESPONSE <<<" 1>&2
    jq -C . <<<"$RES" 1>&2
  fi
  # If the response had "code: 0" then it was successful, otherwise it
  # was an error
  if [ "$(jq -r '.code' <<<"$RES")" -eq "0" ]; then
    jq '.value' <<<"$RES"
    return 0
  else
    echo -n "$CMD ERROR: " 1>&2
    jq -r '"\(.error.detail) (\(.error.rspCode))"' <<< "$RES" 1>&2
    return 1
  fi
}
# Send a Login command to the API
rl-login() {
  rl-api Login "$(
    jq -n --arg USER "$USER" --arg PASS "$PASS" '{
      User: { userName: $USER, password: $PASS }
    }'
  )" | jq -r '.Token.name'
}
# Send a Logout command to the API
rl-logout() {
  if [ "$TOKEN" = "null" ] || [ "$TOKEN" = "" ]; then return; fi
  rl-api Logout > /dev/null
}

# Login with username and password and get a session token
TOKEN="$(rl-login)"
if [ -z "$TOKEN" ]; then exit 1; fi

# Now that we have a token, we add an exit hook to remove it when the
# script exits, if you leave it around you may get the dreaded (and
# annoying) "max session" error.  If that happens all you can really
# do is wait, by default the tokens are good for an hour (and the
# session limit is global, so using multiple usernames won't help)
trap 'rl-logout' EXIT

# Process any arguments on the command line as commands, if the
# command is followed by something that looks like a payload, then
# pass that as the payload to the command.
while (( $# )); do
  CMD="$1" ; shift
  #if (( $# )) && jq -eR 'try(fromjson)' <<<"$1"; then
  if (( $# )) && [[ $1 == *[{}]* ]]; then
    PAYLOAD="$1" ; shift
  else
    PAYLOAD="{}"
  fi
  rl-api "$CMD" "$PAYLOAD" || exit 1
done

## Some Example Commands.md

      
    Raw
  

              Some Example Commands.md
            
          
    List all of your cameras, nicely formatted

./rl-api GetChannelStatus |
  jq -r '.status[] | [.channel,.online,.typeInfo,.name] | @tsv' |
  column -t -s $'\t'
Get abilities for currently logged in user

./rl-api GetAbility '{User:{userName:""}}'
Get abilitiies for specific user

./rl-api GetAbility '{User:{userName:"admin"}}'
Some other useful commands

./rl-api GetDevInfo
./rl-api GetDevName
./rl-api GetTime
./rl-api GetAutoMaint
./rl-api GetHddInfo
./rl-api GetAutoUpgrade
./rl-api GetChannelStatus
./rl-api GetUser
./rl-api GetOnline
./rl-api GetLocalLink
./rl-api GetDdns
./rl-api GetEmail
./rl-api GetFtp
./rl-api GetNtp
./rl-api GetNetPort
./rl-api GetUpnp
./rl-api GetWifi
	#!/bin/bash

	HOST="$REOLINK_NVR_HOST" # Your NVR or Camera IP Address
	USER="$REOLINK_NVR_USER" # Your username
	PASS="$REOLINK_NVR_PASS" # Your password
	# Set this to true and the script will dump the request/response
	# payloads to stderr.
	DEBUG=false

	### END OF CONFIGURATION ###

	URL="https://$HOST/cgi-bin/api.cgi"

	# TOKEN must initially be set to null, so that it gets passed to the
	# login command as `?cmd=Login&token=null`
	TOKEN="null"

	# Takes an API command as the first argument, and JSON-ish payload as
	# an optional second argument. If a payload is provided it's
	# processed with `jq -n` to make it easier (jq -n doesn't require
	# property names to be quoted, you can have trailing commas and other
	# stuff that isn't actually valid JSON)
	rl-api() {
	local CMD="$1" PARAM='{}'
	if [ -n "$2" ]; then PARAM="$(jq -n "$2")"; fi
	local REQ="$(
	jq -n --arg CMD "$CMD" --argjson PARAM "$PARAM" '{
	cmd: $CMD,
	action: 0,
	param: $PARAM,
	}'
	)"
	local TGT="$URL?cmd=$CMD&token=$TOKEN"
	if $DEBUG; then
	echo ">>> REQUEST >>>" 1>&2
	echo "TARGET: $TGT" 1>&2
	jq -C . <<<"$REQ" 1>&2
	fi
	local RES="$(
	curl -kfsSLH 'Content-Type: application/json' -d "[$REQ]" -XPOST "$TGT" \|
	jq '.[0]'
	)"
	if $DEBUG; then
	echo "<<< RESPONSE <<<" 1>&2
	jq -C . <<<"$RES" 1>&2
	fi
	# If the response had "code: 0" then it was successful, otherwise it
	# was an error
	if [ "$(jq -r '.code' <<<"$RES")" -eq "0" ]; then
	jq '.value' <<<"$RES"
	return 0
	else
	echo -n "$CMD ERROR: " 1>&2
	jq -r '"\(.error.detail) (\(.error.rspCode))"' <<< "$RES" 1>&2
	return 1
	fi
	}
	# Send a Login command to the API
	rl-login() {
	rl-api Login "$(
	jq -n --arg USER "$USER" --arg PASS "$PASS" '{
	User: { userName: $USER, password: $PASS }
	}'
	)" \| jq -r '.Token.name'
	}
	# Send a Logout command to the API
	rl-logout() {
	if [ "$TOKEN" = "null" ] \|\| [ "$TOKEN" = "" ]; then return; fi
	rl-api Logout > /dev/null
	}

	# Login with username and password and get a session token
	TOKEN="$(rl-login)"
	if [ -z "$TOKEN" ]; then exit 1; fi

	# Now that we have a token, we add an exit hook to remove it when the
	# script exits, if you leave it around you may get the dreaded (and
	# annoying) "max session" error. If that happens all you can really
	# do is wait, by default the tokens are good for an hour (and the
	# session limit is global, so using multiple usernames won't help)
	trap 'rl-logout' EXIT

	# Process any arguments on the command line as commands, if the
	# command is followed by something that looks like a payload, then
	# pass that as the payload to the command.
	while (( $# )); do
	CMD="$1" ; shift
	#if (( $# )) && jq -eR 'try(fromjson)' <<<"$1"; then
	if (( $# )) && [[ $1 == [{}] ]]; then
	PAYLOAD="$1" ; shift
	else
	PAYLOAD="{}"
	fi
	rl-api "$CMD" "$PAYLOAD" \|\| exit 1
	done