Add per-flock canary limits docs

docs/.vuepress/config.js

@@ -180,6 +180,7 @@ module.exports = {
           '/flocks-settings/overview',
           '/flocks-settings/info',
           '/flocks-settings/notifications',
+          '/flocks-settings/canary-limits',
           '/flocks-settings/change-alerts',
           '/flocks-settings/default-ignore-list',
           '/flocks-settings/hostname-ignore-list',

docs/bird-management/registrations.md

@@ -11,6 +11,21 @@ endpoints:
         type: string
         description: A valid auth token
     response: JSON Structure of Birds pending commissions.
+  flock_pending_commissions:
+    name: Pending Bird Commissions in Flock
+    url: /api/v1/flock/commission/pending
+    method: GET
+    description: Fetch a list of Birds waiting in a specific Flock's pending queue.
+    params:
+      - name: auth_token
+        required: true
+        type: string
+        description: A valid auth token
+      - name: flock_id
+        required: true
+        type: string
+        description: ID of the Flock whose pending queue should be returned
+    response: JSON Structure of Birds pending commissions in the specified Flock.
   cancel_commission:
     name: Cancel Bird Commission
     url: /api/v1/device/cancel_commission
@@ -26,6 +41,21 @@ endpoints:
         type: string
         description: A valid Canary node_id
     response: JSON structure with result indicator.
+  bulk_cancel_commission:
+    name: Bulk Cancel Bird Commission
+    url: /api/v1/device/bulk_cancel_commission
+    method: POST
+    description: Cancel commission for multiple pending Birds.
+    params:
+      - name: auth_token
+        required: true
+        type: string
+        description: A valid auth token
+      - name: node_ids
+        required: true
+        type: string
+        description: A comma-separated list of valid Canary node_ids
+    response: JSON structure with result indicator.
   confirm_commission:
     name: Confirm Bird Commission
     url: /api/v1/device/commission
@@ -44,7 +74,47 @@ endpoints:
         required: false
         type: string
         default: "'flock:default'"
-        description: ID of the flock to assign the Bird to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
+        description: ID of the Flock to assign the Bird to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
+    response: JSON structure with result indicator.
+  assign_pending:
+    name: Assign Pending Bird
+    url: /api/v1/device/assign_pending
+    method: POST
+    description: Assign a pending Bird to a Flock's pending queue.
+    params:
+      - name: auth_token
+        required: true
+        type: string
+        description: A valid auth token
+      - name: node_id
+        required: true
+        type: string
+        description: A valid Canary node_id
+      - name: flock_id
+        required: false
+        type: string
+        default: "'flock:default'"
+        description: ID of the Flock to assign the Bird to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
+    response: JSON structure with the assigned Bird node_id.
+  bulk_assign_pending:
+    name: Bulk Assign Pending Birds
+    url: /api/v1/device/bulk_assign_pending
+    method: POST
+    description: Assign multiple pending Birds to a Flock's pending queue.
+    params:
+      - name: auth_token
+        required: true
+        type: string
+        description: A valid auth token
+      - name: node_ids
+        required: true
+        type: string
+        description: A comma-separated list of valid Canary node_ids
+      - name: flock_id
+        required: false
+        type: string
+        default: "'flock:default'"
+        description: ID of the Flock to assign the Birds to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
     response: JSON structure with result indicator.
   decommission_device:
     name: Decommission Bird
@@ -148,6 +218,74 @@ print(r.json())
 
 </APIDetails>
 
+## Pending Bird Commissions in Flock
+
+<APIDetails :endpoint="$page.frontmatter.endpoints.flock_pending_commissions">
+
+::::: slot description
+
+Fetch all Birds currently waiting in a specific [Flock pending queue](/guide/terminology.html#flock-pending-queues).
+
+:::::
+
+::::: slot example
+
+:::: tabs :options="{ useUrlFragment: false }"
+
+::: tab "cURL"
+
+``` bash
+curl https://EXAMPLE.canary.tools/api/v1/flock/commission/pending \
+  -d auth_token=EXAMPLE_AUTH_TOKEN \
+  -d flock_id=EXAMPLE_FLOCK_ID \
+  -G
+```
+
+:::
+
+::: tab "Python"
+
+``` python
+import requests
+
+url = 'https://EXAMPLE.canary.tools/api/v1/flock/commission/pending'
+
+payload = {
+  'auth_token': 'EXAMPLE_AUTH_TOKEN',
+  'flock_id': 'EXAMPLE_FLOCK_ID'
+}
+
+r = requests.get(url, params=payload)
+
+print(r.json())
+```
+
+:::
+
+::::
+
+::: api-response
+```json
+{
+  "devices": [
+    {
+      "description": "",
+      "device_id": "<node_id>",
+      "device_version": "4.1.2",
+      "name": "example-bird",
+      "pending_since": 1765376090.035862,
+      "sensor": "thinkstcanary"
+    }
+  ],
+  "result": "success"
+}
+```
+:::
+
+:::::
+
+</APIDetails>
+
 ## Cancel Bird Commission
 
 <APIDetails :endpoint="$page.frontmatter.endpoints.cancel_commission">
@@ -188,6 +326,63 @@ print(r.json())
 ::::
 
 
+::: api-response
+```json
+{
+  "result": "success"
+}
+```
+:::
+
+:::::
+
+</APIDetails>
+
+## Bulk Cancel Bird Commission
+
+<APIDetails :endpoint="$page.frontmatter.endpoints.bulk_cancel_commission">
+
+::::: slot description
+
+Cancel commission for multiple Birds in one request. The supplied `node_ids` must be a comma-separated list of pending Birds.
+
+:::::
+
+::::: slot example
+
+:::: tabs :options="{ useUrlFragment: false }"
+
+::: tab "cURL"
+
+``` bash
+curl https://EXAMPLE.canary.tools/api/v1/device/bulk_cancel_commission \
+  -d auth_token=EXAMPLE_AUTH_TOKEN \
+  -d node_ids=EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2
+```
+
+:::
+
+::: tab "Python"
+
+``` python
+import requests
+
+url = 'https://EXAMPLE.canary.tools/api/v1/device/bulk_cancel_commission'
+
+payload = {
+  'auth_token': 'EXAMPLE_AUTH_TOKEN',
+  'node_ids': 'EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2'
+}
+
+r = requests.post(url, data=payload)
+
+print(r.json())
+```
+
+:::
+
+::::
+
 ::: api-response
 ```json
 {
@@ -253,6 +448,125 @@ print(r.json())
 
 </APIDetails>
 
+## Assign Pending Bird
+
+<APIDetails :endpoint="$page.frontmatter.endpoints.assign_pending">
+
+::::: slot description
+
+Assign a pending Bird to a specific Flock's pending queue. If the destination Flock has available space, the Bird will be commissioned immediately.
+
+:::::
+
+::::: slot example
+
+:::: tabs :options="{ useUrlFragment: false }"
+
+::: tab "cURL"
+
+``` bash
+curl https://EXAMPLE.canary.tools/api/v1/device/assign_pending \
+  -d auth_token=EXAMPLE_AUTH_TOKEN \
+  -d node_id=EXAMPLE_NODE_ID \
+  -d flock_id=EXAMPLE_FLOCK_ID
+```
+
+:::
+
+::: tab "Python"
+
+``` python
+import requests
+
+url = 'https://EXAMPLE.canary.tools/api/v1/device/assign_pending'
+
+payload = {
+  'auth_token': 'EXAMPLE_AUTH_TOKEN',
+  'node_id': 'EXAMPLE_NODE_ID',
+  'flock_id': 'EXAMPLE_FLOCK_ID'
+}
+
+r = requests.post(url, data=payload)
+
+print(r.json())
+```
+
+:::
+
+::::
+
+::: api-response
+```json
+{
+  "node_id": "<node_id>",
+  "result": "success"
+}
+```
+:::
+
+:::::
+
+</APIDetails>
+
+## Bulk Assign Pending Birds
+
+<APIDetails :endpoint="$page.frontmatter.endpoints.bulk_assign_pending">
+
+::::: slot description
+
+Assign multiple pending Birds to a specific Flock's pending queue in a single request.
+
+:::::
+
+::::: slot example
+
+:::: tabs :options="{ useUrlFragment: false }"
+
+::: tab "cURL"
+
+``` bash
+curl https://EXAMPLE.canary.tools/api/v1/device/bulk_assign_pending \
+  -d auth_token=EXAMPLE_AUTH_TOKEN \
+  -d node_ids=EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2 \
+  -d flock_id=EXAMPLE_FLOCK_ID
+```
+
+:::
+
+::: tab "Python"
+
+``` python
+import requests
+
+url = 'https://EXAMPLE.canary.tools/api/v1/device/bulk_assign_pending'
+
+payload = {
+  'auth_token': 'EXAMPLE_AUTH_TOKEN',
+  'node_ids': 'EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2',
+  'flock_id': 'EXAMPLE_FLOCK_ID'
+}
+
+r = requests.post(url, data=payload)
+
+print(r.json())
+```
+
+:::
+
+::::
+
+::: api-response
+```json
+{
+  "result": "success"
+}
+```
+:::
+
+:::::
+
+</APIDetails>
+
 ## Decommission Bird
 
 ::: warning
@@ -309,4 +623,4 @@ print(r.json())
 
 :::::
 
-</APIDetails>
+</APIDetails>

docs/bird-management/updates.md

@@ -44,7 +44,7 @@ endpoints:
         required: false
         type: string
         default: "'flock:default'"
-        description: ID of the flock to assign the Bird to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
+        description: ID of the Flock to assign the Bird to (defaults to the [Default Flock](/guide/terminology.html#default-flock)).
     response: A JSON structure with the list of Birds that are currently updating.
   list_updates:
     name: List Updates

docs/breadcrumbs/mass-deployment.md

@@ -7,5 +7,5 @@ To make this easier for you, Breadcrumbs can be mass deployed by making use of r
 Read-only Flock API keys can be generated via the "[Flock API Key endpoints](/flocks-settings/flock-auth-token.html)" and setting `auth_token_type` to `read-only`.
 
 ::: warning
-While read-only Flock API auth keys limit which devices can be viewed to a specific flock, it is recommended that they be disabled after they are used by scripts to deploy breadcrumbs. This can be done via the "[Remove Flock API key](/flocks-settings/flock-auth-token.html#remove-flock-api-key)" endpoint.
+While read-only Flock API auth keys limit which devices can be viewed to a specific Flock, it is recommended that they be disabled after they are used by scripts to deploy breadcrumbs. This can be done via the "[Remove Flock API key](/flocks-settings/flock-auth-token.html#remove-flock-api-key)" endpoint.
 :::

docs/canarytokens/factory.md

@@ -199,7 +199,7 @@ The Canarytoken factory gives you a limited use key that is able to create other
 ::: warning NOTE
 We recommend that you use the Canarytoken Deploy [Flock API Key type](/flocks-settings/flock-auth-token.html), instead of Factory Auth Tokens.
 
-The Canarytoken Deploy Flock API type is specifically designed to only be able to create and download (deploy) Canarytokens within a specific flock, and can be viewed/managed from the Console UI [Flock API settings](https://help.canary.tools/hc/en-gb/articles/7111549805213-Flock-API-Keys) in the same way as your other Flock API keys.
+The Canarytoken Deploy Flock API type is specifically designed to only be able to create and download (deploy) Canarytokens within a specific Flock, and can be viewed/managed from the Console UI [Flock API settings](https://help.canary.tools/hc/en-gb/articles/7111549805213-Flock-API-Keys) in the same way as your other Flock API keys.
 
 Existing Canarytoken Factory Endpoints and factory auth strings continue to work as before to support existing deployments. They are now simpler to manage in the Console UI as they're transparently converted to Canarytoken Deploy Flock API keys.
 :::