API Fields

This page distills field-level details from the current DTO and route implementations, focusing on the common responses, event queries, event records, HTTP push parameters, and MQTT parameters that are most commonly used by public integrations. A complete OpenAPI schema can be generated from these DTOs later.

Common Response

Field	Type	Description
resCode	number	CWAI response code; 1 = success, 0 = failure
resMsg	object[]	Error or info message list
resMsg[].msgCode	string	Message code
resMsg[].msgText	string	Message text
resMsg[].messageKey	string	Stable localization key; frontends should prefer it for translation
resMsg[].details	object	Machine-readable actual values, limits, required resources, and currently available resources
resMsg[].retryable	boolean	Whether retrying can help after external conditions change
resMsg[].retryAfterSeconds	number	Suggested delay in seconds, returned only when applicable
resMsg[].recommendedAction	string	Suggested next step, such as freeing storage, switching to chunks, or resizing an image
resultCode	string	ChinaMobile-compatible response code
resultMsg	string	ChinaMobile-compatible response text
resData	object	Business response data

messageKey, details, recommendedAction, and retryAfterSeconds are returned only when applicable; retryable can also be omitted when false. Clients must treat an absent field as “no additional guidance,” not as another failure.

Chunk Upload Fields

See API Overview: Resource-Aware Transfers for the capability, chunk, and cancellation endpoints. uploadTemp uses multipart/form-data:

Field	Type	First Chunk	Later Chunks	Description
file	blob	required	required	Current chunk; the filename must remain unchanged
purpose	string	required	required	model-component, model-archive, video, face-import, audio, algorithm, upgrade, or image
chunkIndex	decimal string	0	required	Zero-based chunk index
totalChunks	decimal string	required	required	Chunk count for the complete file
totalSize	decimal string	required	required	Complete file size in bytes
chunkSize	decimal string	required	required	Current chunk size; it must match the actual multipart file size
clientRequestId	string	recommended	unchanged	Stable principal-scoped resume identity, up to 128 characters
uploadId	string	omitted	required	Opaque server-issued session ID
sha256	string	optional	unchanged	64-character hexadecimal SHA-256 of the complete file

contentLength, fileName, and filePath are generated by the server-side multipart parser from the current request. Client-supplied fields with those names are not trusted sources.

uploadTemp returns these fields under resData:

Field	Type	Description
uploadId	string	Server session ID required by subsequent chunks and the business consumer
nextChunkIndex	decimal string	Next chunk required by the server; it can jump over confirmed chunks after an idempotent replay or restart recovery
complete	boolean	Whether the complete file has been received and verified
filePath	string	R1-compatible opaque upload:// alias; it is not a server path and new clients must not use it

After upload completion, business APIs reference only the session ID:

Business Endpoint	Field
/gtw/cwai/Camera/AddVideo	uploadId
/gtw/cwai/aihost/PTaskDetectPic	uploadId, mutually exclusive with imageBase64/imageUrl
/gtw/cwai/Library/ModifyFacePicLib	pictureUploadIds[]
/gtw/cwai/BodyLibrary/DetectPerson	uploadId
/gtw/cwai/ThingsLibrary/AddLibThings	thingsList[].pictureUploadId

Model components, model archives, algorithm packages, upgrade packages, audio, and face imports likewise use the uploadId field in their respective DTOs. Legacy Base64 and compatibility fields remain readable, but large-file and high-resolution-image clients should use staged sessions and must not rely on server paths.

Pagination and Time Range

Event queries and similar interfaces reuse the pagination and time fields:

Field	Type	Default	Description
pageNum	number	1	Page number
pageSize	number	10	Page size
timeBegin	number	0	Start time, millisecond timestamp
timeEnd	number	0	End time, millisecond timestamp

Event Query Conditions

Source: MsgConditionEvent.

Field	Type	Description
algorithmCodes	string[]	Algorithm code list
categorys	string[]	Event category list (field name retained from the current implementation)
videoChannelName	string	Channel name
personName	string	Person name
personCode	string	Person code
matchLibName	string	Matched gallery name
propColor	string	Target color, often vehicle color
propRelatedColor	string	Related target color, often plate color
propType	string	Target type, often vehicle type
propDirection	string	Target direction, often vehicle direction
reportStatus	number	Report status, default -1

Event Record

Source: MsgEventUnit.

Field	Type	Description
id	string	Event record ID
videoChannelId	string	Video channel ID
channelCode	string	Channel code
channelName	string	Channel name
timestamp	number	Event time, millisecond timestamp
category	string	Event category
algorithmCode	string	Algorithm code
algorithmName	string	Algorithm name
areaId	string	Area ID
areaName	string	Area name
fullPicture	string	Full-frame image URL
detectedPicture	string	Target detection image URL
video	string	Alarm video URL
videostructured	string	Structured video file URL
reportStatus	number	Report status
property	string	Attribute JSON string; varies by algorithm type

Event Report Payload

HTTP webhook and some internal event messages use CMsgOnEventsReq semantics:

Field	Type	Description
messageId	string	Message ID
devId	string	Device ID
taskId	string	Task ID
videoChannelId	string	Channel ID
channelName	string	Channel name
timestamp	string	UTC millisecond timestamp string
itimestamp	number	UTC millisecond timestamp (defined in the DTO; the current outbound to_json does not output this field, only inbound deserialization reads it)
algorithmId	string	Algorithm ID
algorithmCode	string	Algorithm code
algorithmName	string	Algorithm name
areaId	string	Area ID
areaName	string	Area name
orignalPicture	string	Original image: Base64 in HTTP webhooks and a URL in internal messages (field name retained from the current implementation)
fullPicture	string	Full-frame image: Base64 in HTTP webhooks and a URL in internal messages
detectedPicture	string	Target image: Base64 in HTTP webhooks and a URL in internal messages
video	string	Alarm video: an absolute device-local path in standalone HTTP webhooks and a web URL in browser/query responses. The file may take a few seconds to finish after the event is pushed
videostructured	string	Structured video file path or URL; may be empty
overviewFile	string	Structured overview file path or URL; may be empty
recordId	string	Alarm record ID
files	string[]	Related file list (defined in the DTO; the current outbound to_json does not output this field, only inbound deserialization reads it)
isRetryMessage	boolean	Whether this is a retry message
targets	object[]	Detection targets that triggered the event, with label, confidence, optional trackId, and pixel-coordinate box
property	object	Attribute object; varies by algorithm type
category	string	Event category

Property Field Types

Event properties are differentiated via OnEventsPropertyType (see the enum in src/util/MsgBaseTypes.h, and the outbound serialization in src/util/dto/ClientMsgEvent.cc). Each type outputs its corresponding JSON key:

Type (OnEventsPropertyType)	Output Key	Main Fields
face	face	quality, age, gender, wearMask, wearGlasses, featureUrl, image
body (Body / BodyFeature)	body	topLength, topColor, bottomLength, bottomColor, featureUrl, image
vehicle	vehicle	plateColor, vehicleColor, vehicleClass, orientation, plate, plateSrc, attrs
behavior	behavior	count, duration, targetId
machineMaterial	machineMaterial	matchId, matchDegree, groupId, groupName, baseImageUrl, runningStatus
people	people	enterNumber, leaveNumber, enterOrgNum, leaveOrgNum, time
car	car	enterNumber, leaveNumber, enterOrgNum, leaveOrgNum, time
workClothesRecognition	workClothesRecognition	matchId, matchDegree, groupId, groupName, baseImageUrl
personCount (PersonCount)	personCount + persons	Area person-count statistics; also outputs the persons list (fields below)
countNumber (CountNumber)	countNumber	Counting-type events

The following are additional sub-objects (not independent OnEventsPropertyType enum values, but emitted alongside the main type):

Sub-object	Emitted When	Main Fields
recognition	Emitted alongside the face type	matchDegree, matchLibName, matchId, LibImage, matchName, personCode, personId
persons	Emitted alongside the personCount type	orignalPicture, fullPicture, targetPicture, box
target	Any type, appended when bHaveTarget is true	inAreaTime, inAreaFullImageUrl, outAreaTime, outAreaFullImageUrl

HTTP Push Parameters

Routes:

/gtw/cwai/System/QueryHttpInterfaceParam
/gtw/cwai/System/SetHttpInterfaceParam

Field	Type	Description
switch	boolean	Whether HTTP push is enabled; the set interface only recognizes this field
enable	boolean	Only output by the query response (same value as switch); the set interface does not read this field
url	string	HTTP URL that receives events

MQTT Parameters

Routes:

/gtw/cwai/System/QueryMqttAdapterParam
/gtw/cwai/System/SetMqttAdapterParam

Field	Type	Default	Description
switch	boolean	true	Whether MQTT is enabled; the set interface only recognizes this field
enable	boolean	true	Only output by the query response (same value as switch); the set interface does not read this field
url	string	empty	MQTT broker address
port	number	1883	MQTT broker port
status	boolean	true	Current MQTT registration/connection status; a query-result field
authMode	number	0	0 uses built-in IoT auth; non-0 uses a normal username/password
clientId	string	empty	Client ID under normal auth mode
userName	string	empty	Username under normal auth mode
passwd	string	empty	Password under normal auth mode

IoT Network Mode Parameters

Routes:

/gtw/cwai/System/QueryIotNetworkParam
/gtw/cwai/System/ModifyIotNetworkParam

Field	Type	Default	Description
mqttIp	string	empty	MQTT address under IoT network mode
mqttPort	number	1883	MQTT port under IoT network mode
httpUrl	string	empty	HTTP address under IoT network mode
status	boolean	true	Whether MQTT is currently enabled; a query-result field