General API rules
The API is the contract of the specific installed version. Open Help → API and use its current schema. BOX 3.2 field examples help explain their purpose but do not replace the BOX 5.0 contract.
| Concept | How to use |
|---|---|
required |
The key must be present; whether an empty string is allowed is determined by separate validation |
| ID / UUID / name | Different fields. Obtain IDs from the catalog, not table row numbers |
null / empty array / omitted key |
Not interchangeable, especially during a partial update |
| Time | Confirm the time zone, format, and units; distinguish frame time from registration time |
| Coordinates | Confirm pixels or fractions, image size, and point order |
| Pagination | Process every page and check the count and unique IDs |
| Write operation | Read the current entity first; preserve fields and relationships you are not changing |
Camera and analytics assignment
Integration requires the name, source type, address/identifier, site, camera/analytics/recording states, and connection parameters. BOX-family schemas include name, media_uri, camera_type, object_id, is_enabled, is_record, is_disable_inference. The last is an inverse flag: disabling analytics must not be confused with enabling it.
In BOX 5.0, also account for scenario assignments: scenario ID, version ID/number, individual parameters, and uniqueness and inheritance flags. Use your build's schema for exact JSON field names and assignment operations. They cannot be reconstructed from a tab name or automatically inferred from the BOX 3.2 field categories_presets.
Zones, presets, and graphs
A zone has an ID, type/code, name, color, and geometry. A preset has a set of categories and parameters. A scenario has a card, a version, and logic. Do not serialize these entities as one object merely because the same camera uses them.
For a graph, retain model dependencies and versions. When transferring between installations, map resource IDs, zone-type directories, and categories. A JSON copy containing old IDs can be syntactically correct but semantically wrong.
Events and decisions
An event is associated with a camera, time, category, scenario/version for scenario-based processing, and media. An operator decision and a classification change are separate actions with history. For a report, retain the original category, current category, decision status, and ID.
A processing failure, rejected event, unreviewed event, and absence of events are different states. HTTP success when retrieving a list does not establish completeness without checking filters and pagination.
Assets, models, and runs
Automation must record the resource and its version, not just a mutable name. Wait for the final status of an asynchronous operation. Package upload, validation, conversion, and execution-on-data failures require different remedies.
For a reproducible test, retain the scenario/model and version, asset and version, run parameters, status, results, and time. Submitting a run request does not complete validation.
Presence intervals and reporting
Calculating workplace occupancy requires interval boundaries, the schedule, and observation reliability data. An aggregate people count, latest event, and violation list do not by themselves provide total presence time.
The scenario-based implementation §4.17 must supply an agreed contract for intervals or pairs of start/end events. Specify rules for incomplete intervals, stream interruptions, repeats, and shift boundaries. Integration with the standard workplace attendance report must be checked separately.
LLM and MCP
For LLM, distinguish service configuration, prompt, instruction version/content, schedule, and the result of an individual call. Category and bounding-box formats must match the consumer. An HTTP 200 response containing text does not guarantee that the BOX handler accepted the response.
MCP provides domain-specific operations over permitted data. Request the tool catalog from the connected server; do not assume different releases have identical sets. The reporting method and completeness limitations are described in §14.5.