Access points reported by the wireless controllers Yagra monitors.

GET

/api/v1/wireless/aps

curl --request GET \
  --url https://example.com/api/v1/wireless/aps \
  --header 'Authorization: Bearer <token>'

Built from each controller’s AP table on every poll, so an AP is listed whether or not it has been imported as a node. An AP behind an HA pair appears once: state and clients are what the controller serving it says, and reported_by shows every controller’s view. An AP that no controller reports any more stays in the list with its last_seen ageing.

Authorizations

• bearer

Parameters

Query Parameters

controller_node_id

string format: uuid

Only APs this controller node reports.

state

string

Only APs in this state: associated, backup or not_associated.

search

string

A case-insensitive substring of the name, MAC address, IP address or model (at most 64 characters). Matched literally.

limit

integer format: int64

Page size, 1–2048 (default 200).

after_key

string

Keyset cursor: next.key from the previous page. Pair with after_id.

after_id

string format: uuid

Keyset cursor: next.ap_id from the previous page. Pair with after_key.

Responses

200

One page of access points, ordered by name

Media typeapplication/json

One page of access points, ordered by name.

object

aps

required

Array<object>

One access point.

object

ap_id

required

Stable id, derived from the MAC address. The same AP keeps it when the controller serving it changes.

string format: uuid

clients

Wireless clients online through this AP, as the serving controller reports it.

integer | null format: int32

controller_node_id

The node of the controller serving this AP: the last one to report it in service.

string | null format: uuid

first_seen

required

When a controller first reported this AP (RFC 3339).

string

ip

Management address. null when the controller reports none, which it does for an AP that is down.

string | null

last_associated_at

When a controller last reported this AP in service (RFC 3339). null if it never has been.

string | null

last_seen

required

When a controller last reported this AP (RFC 3339). It stops advancing when no controller reports the AP any more; the AP is never removed.

string

mac

required

MAC address, lower-case and colon-separated.

string

model

Model, as the controller spells it.

string | null

name

The AP’s name on its controller.

string | null

node_id

The AP’s node, once it has been imported as one.

string | null format: uuid

reported_by

required

What each controller that reports this AP says, the serving controller first. Two entries for an AP behind an HA pair.

Array<object>

One controller’s view of one access point.

object

clients

integer | null format: int32

controller_node_id

The reporting controller’s node.

string | null format: uuid

last_associated_at

When this controller last reported the AP in service (RFC 3339).

string | null

last_seen

required

When this controller last reported the AP (RFC 3339).

string

run_state

required

string

state

One of:

null

null

string

What one controller says about one AP, reduced to the three answers the system acts on (ADR-064 revision R5).

string

Allowed values: associated backup not_associated

run_state

required

The controller’s own word for the state (normal, fault, standby).

string

serial

string | null

state

One of:

null

null

string

What the serving controller says: associated (in service), backup (a standby controller’s view) or not_associated (down, not yet joined, or failing). null for a state this server version does not recognise.

string

Allowed values: associated backup not_associated

sw_version

Software version.

string | null

vendor_group

The vendor’s own grouping of APs (a Huawei AP group).

string | null

controller

One of:

null

null

object

The controller named by controller_node_id, when one was named, the caller can see it, and it has either reported an inventory or had its import settings saved (then last_inventory_at is null). null otherwise.

object

ap_group_id

The folder imported AP nodes are filed in. null ⇒ the folder this controller is in. No folder is created for them.

string | null format: uuid

aps_over_cap

required

How many access points the max_aps cap left out on the last import pass.

integer format: int32

aps_reported

required

How many APs its last inventory carried.

integer format: int32

aps_truncated_at

Set when the controller reported more APs than one inventory may carry: how many it reported. The list then holds only the first ones by MAC address.

integer | null format: int32

flavor

One of:

null

null

string

The vendor dialect its AP table was read in. null until an inventory has arrived.

string

Allowed values: huawei cisco_airespace

import_aps

required

Whether access points this controller reports become nodes. On by default for a controller Yagra has just started reading; only APs that have been in service at least once are imported automatically.

boolean

last_inventory_at

When its last complete inventory arrived (RFC 3339). null if none has.

string | null

max_aps

required

The most access points this controller imports (1–2048).

integer format: int32

node_id

required

The controller’s node.

string format: uuid

next

One of:

null

null

object

null ⇒ this was the last page.

object

ap_id

required

Pass back as after_id.

string format: uuid

key

required

Pass back as after_key.

string

Example

{
  "aps": [
    {
      "reported_by": [
        {
          "state": "associated"
        }
      ],
      "state": "associated"
    }
  ],
  "controller": {
    "flavor": "huawei"
  }
}

400

Unknown state, search longer than 64 characters, or only one half of the cursor

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks View

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Inventory storage is unavailable (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}