Returns DHCP events for a specific device with filtering support

GET

/api/history/device/{mac}/events

• Your DHCP Shield Pro appliance

Auto-generated from server.go. Handler: s.getDeviceHistory.

Supports format=csv query param for CSV export — the operation carries x-validation: skip (D-120) because the CSV branch is not JSON.

Authorizations

• bearerAuth

Parameters

Path Parameters

mac

required

string

/^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/

Example

aa:bb:cc:dd:ee:ff

Full MAC address with colon or hyphen separators.

Query Parameters

format

string

default: json

Allowed values: json csv

Responses

200

Successful response

Returns DHCP events for a specific device with filtering support.

Schema hand-rewritten in Session 10 to share the HistoryEventItem component (events array now $refs HistoryEventItem rather than redeclaring inline). The original Session-6 lift carried an inline events item that was a strict subset of the Go HistoryEventItem (missing all DHCPv6 omitempty fields). The shared component carries the full field set with omitempties marked optional.

object

mac

required

string

time_range

required

object

from

required

RFC3339 string emitted by handler time.Time.Format.

string

to

required

RFC3339 string emitted by handler time.Time.Format.

string

filters

required

object

time_range

required

object

from

required

string

to

required

string

message_types

Omitempty in Go.

Array<string>

sort

required

object

field

required

string

order

required

string

events

required

Array<object>

A single DHCP event row from history. Many fields are optional (omitempty in Go) — DHCPv6 fields are only present for v6 events, DHCPv4 packet fields only for v4 events. Required fields below are those the lift saw populated in the seed sample; treat the rest as optional.

Hand-extracted in Session 10 from internal/api/models.go::HistoryEventItem so both /api/history/events and /api/history/device/{mac}/events can reference the same shape.

object

timestamp

required

RFC3339Nano formatted; emitted by handler as string.

string

client_mac

required

string

source_mac

required

string

source_ip

required

string

message_type

required

string

xid

required

string

server_ip

required

string

relay_ip

required

string

gateway_ip

required

string

hostname

required

string

vendor_class

required

string

client_identifier

required

string

client_ip

required

string

your_ip

required

string

requested_ip

required

string

lease_time

required

integer

renewal_time

required

integer

rebinding_time

required

integer

mark

required

integer

matched_rule

required

string

processing_time_ms

required

number

dhcp_options

required

string

option_count

required

integer

option_codes

required

string

dest_ip

required

string

source_port

required

integer

dest_port

required

integer

dest_mac

required

string

op_code

required

string

hw_type

required

string

hw_length

required

integer

hop_count

required

integer

seconds

required

integer

flags

required

string

server_hostname

required

string

boot_filename

required

string

server_identifier

required

string

protocol

required

string

client_duid

DHCPv6 only; omitempty.

string

server_duid

DHCPv6 only; omitempty.

string

duid_type

required

string

ia_type

required

string

iaid

DHCPv6 only; omitempty.

integer

ia_addresses

DHCPv6 only; omitempty.

Array<string>

ia_prefixes

DHCPv6 only; omitempty.

Array<string>

delegated_prefix

DHCPv6 only; omitempty.

string

prefix_length

DHCPv6 only; omitempty.

integer

preferred_lifetime

DHCPv6 only; omitempty.

integer

valid_lifetime

DHCPv6 only; omitempty.

integer

link_address

DHCPv6 only; omitempty.

string

peer_address

DHCPv6 only; omitempty.

string

interface_id

DHCPv6 only; omitempty.

string

remote_id

DHCPv6 only; omitempty.

string

subscriber_id

DHCPv6 only; omitempty.

string

user_class

DHCPv6 only; omitempty.

string

vendor_enterprise_id

DHCPv6 only; omitempty.

integer

summary

required

object

total_events

required

integer

events_returned

required

integer

truncated

required

boolean

message_type_counts

required

Dynamic map keyed by DHCP message type.

object

key

additional properties

integer

first_seen

Omitempty in Go — present only when at least one event matched.

string

last_seen

Omitempty in Go.

string

dhcpv6_details

DHCPv6 IA / option detail extracted from the most-recent v6 packet in the window. omitempty in Go; absent for v4 devices.

object

key

additional properties

any

string format: binary

401

Authentication is required or the supplied token is invalid.

Standardised error envelope per RFC 7807. Many existing endpoints still return an older shape (e.g. {"error": "..."}). This schema documents the target shape; legacy endpoints will be migrated in Phase 70. Per D-21 the spec describes current behaviour without enforcing the migration here.

object

type

A URI reference that identifies the problem type.

string format: uri-reference

default: about:blank

title

A short human-readable summary of the problem.

string

status

The HTTP status code generated by the origin server.

integer format: int32

>= 100 <= 599

detail

A human-readable explanation specific to this occurrence.

string

instance

A URI reference that identifies the specific occurrence.

string format: uri-reference

error

Legacy error message field. Will be removed once handlers are migrated.

string

details

Legacy per-field error details. Will be removed once handlers are migrated.

object

key

additional properties

string

requestId

The request id middleware-assigned identifier for tracing.

string

404

The requested resource was not found.

Standardised error envelope per RFC 7807. Many existing endpoints still return an older shape (e.g. {"error": "..."}). This schema documents the target shape; legacy endpoints will be migrated in Phase 70. Per D-21 the spec describes current behaviour without enforcing the migration here.

object

type

A URI reference that identifies the problem type.

string format: uri-reference

default: about:blank

title

A short human-readable summary of the problem.

string

status

The HTTP status code generated by the origin server.

integer format: int32

>= 100 <= 599

detail

A human-readable explanation specific to this occurrence.

string

instance

A URI reference that identifies the specific occurrence.

string format: uri-reference

error

Legacy error message field. Will be removed once handlers are migrated.

string

details

Legacy per-field error details. Will be removed once handlers are migrated.

object

key

additional properties

string

requestId

The request id middleware-assigned identifier for tracing.

string

500

Internal server error

Standardised error envelope per RFC 7807. Many existing endpoints still return an older shape (e.g. {"error": "..."}). This schema documents the target shape; legacy endpoints will be migrated in Phase 70. Per D-21 the spec describes current behaviour without enforcing the migration here.

object

type

A URI reference that identifies the problem type.

string format: uri-reference

default: about:blank

title

A short human-readable summary of the problem.

string

status

The HTTP status code generated by the origin server.

integer format: int32

>= 100 <= 599

detail

A human-readable explanation specific to this occurrence.

string

instance

A URI reference that identifies the specific occurrence.

string format: uri-reference

error

Legacy error message field. Will be removed once handlers are migrated.

string

details

Legacy per-field error details. Will be removed once handlers are migrated.

object

key

additional properties

string

requestId

The request id middleware-assigned identifier for tracing.

string